The state of the space around the time I started was as follows :

• Tutorials inferior to an hour in length were not in demand. They made very little views.

• Tutorials divided into multiple parts where dead on arrival. You were guaranteed dwindling views on every new upload.

To adapt, other content creators started uploading longer, multi-hour, often project based tutorials which translated to more views. Seeing the shift, I also decided to follow suit and uploaded tutorials reaching the 4-10 hour mark. I saw some success doing this. Therefore, I kept at it for a while. However, as time passed, I got tired of recording extremely long tutorials and they, in general, started to make less views.

There are many hypotheses as to why YouTube’s algorithm started serving tutorial content less. The advent of AI could’ve been the likely cause but also a general shift in YouTube becoming more of an entertainment focused platform to the detriment of educational content. Something you now put on TV to relax. In the programming space, channel producing content that can be watched passively like tech news, tech drama, tech history, high level discussions, etc… continued to thrive.

Seeing this new shift and because I was genuinely tired of making YouTube tutorials, I published my first scripted video titled “How do Devs Make Levels Without Game Engines” which was first published as an article.

In that piece, I told the story of how I discovered a convenient way to design levels for my games using an external editor called Tiled in conjunction with my editor-less game framework. At the end of that video, I promoted a paid tutorial I made teaching the exact steps needed to achieve what was presented.

The video ended up accumulating over 30k views, which was pretty great! It took far less effort to make compared to my multi-hour tutorials and I was able to make a few sales on my paid tutorial I mentioned within. Previously, I was very unsuccessful in selling any paid courses and I didn’t quite understand why. However, the answer now hit me like a truck. Why would anyone still have the appetite for a paid course after having invested the time following a free multi-hour course? Even if the subject of the paid offering was different, they would probably be too tired to commit to another one.

Anyway, following in the footsteps of this first breakthrough, I uploaded another scripted video titled “You Can Now Make PS2 Games in JavaScript” which was again first published as an article.

In that video, I told the story of how I discovered that you could make PS2 games in JavaScript and provided an overview of how the viewer could get started. Despite including very practical knowledge, the viewer was never expected to follow along and therefore could watch it passively.

It was a resounding success, over 100k views! Unfortunately, I didn’t sell any courses in that video because I simply didn’t have the energy to both make the video and a course. The best business decision would have been to wait before uploading. I’ll go into more details later, but my biggest gripe with YouTube is that it’s no longer a great platform to build an audience but rather it’s only good for reach and here, I had wasted a lot of reach.

After having made so many game development tutorials, I wanted to try my hand in creating an original game that I would sell on Steam. Once the project was starting to take shape, I had the idea of making a video about it to gauge interest as I wasn’t sure it would find an audience. Therefore, I had the idea of using the same format used in my two previous successful videos. However, rather than focusing on technical details, I instead would tell the story of how I came up with my game’s design covering the various iterations and challenges I faced while working on it. Therefore, I ended up uploading a video titled “Making a Small RPG” which again, was originally an article.

It was also a resounding success reaching barely below 100k views! However, it came with a hidden cost. That cost was the tipping point that made me realize that YouTube is no longer a good platform to build an audience on. I naively thought that if the video performed well, this would translate to subscribers and an audience eager to hear more about the project, but this wasn’t the case. I had made a big mistake by not setting up a Steam page to direct viewers to before publishing the video. On my next upload concerning the project, the fall off in terms of views was brutal. I went from 98k views to below 10k. It became clear that YouTube was acting as a gatekeeper between me and the audience I thought I had built.

After reflecting on the situation, I came to the following conclusion. The reason my 3 previous videos had performed well was due having certain characteristics that aligned with YouTube’s goal as a platform, which consists in making people watch videos for as long as possible so they can serve more ads. I listed them below :

1. The subject of all three videos were remarkable which lead to people clicking on them. Something is remarkable when it obviously stands out as being interesting/noteworthy. For example, the subject of my video titled “You Can Now Make PS2 Games in JavaScript” is remarkable because the PS2 is a very popular, but now old console and you had to use a hard programming language called C++ to make games for it. Being able to now use JavaScript, a simpler but most importantly, a language originally designed for making websites and not games, makes the subject come across as immediately noteworthy. Therefore, remarkable.

2. The use of storytelling made people eager to watch more of the video. This can be explained by the fact that we instinctively want to know what happens next in a compelling story.

3. Finally, the length of the videos were all above 10 minutes and the 2 more successful ones were in the 15+ min range. This resulted in more absolute watch time compared to shorter content. For example, if 2 videos are both watched fully by the same audience. The shorter one will translate to less total time spent on the platform compared to the longer one. Therefore, YouTube will recommend the longer one instead because there’s an opportunity cost to doing otherwise.

To understand the fall off, it’s important to first mention that usually, series on YouTube don’t work. The second video of a series ends up making less views than the first because it requires prior context before clicking. Thus reducing its appeal and limiting its reach. However, I knew this going in. I tried making the second video as independent as possible but in the end, a second video talking about the same subject was bound to be less remarkable. It didn’t help that because I summarized the content of the first video in the second one, a familiar viewer would have found it less engaging making the video further away from hitting criteria 2 and 3 that I outlined above.

Consequently, I realized I had wasted my biggest marketing ammunition regarding my small RPG game as I had no way to contact the audience hit by the first video. Like with the one on making PS2 games in JavaScript, I had wasted tremendous reach.

At this point, I realized my biggest gripe with YouTube was simply that I could not access my audience reliably. Therefore, was it really my audience? On one hand, YouTube allows someone without a following to reach millions but on the other, the link to those reached is fickle. I thought I was building an audience by gaining subscribers but instead, I was building a sand castle that could easily be carried away by the slightest algorithm waves.

YouTube wasn’t always like this. People used to subscribe to channels and seek their content in their subscriptions tab. However, the platform effectively buried this model by conditioning users to seek recommended videos on the home page and deprioritizing the Subscriptions tab to the point that it barely looks like a clickable section.

I think that we’re now entering an era where YouTube is starting to treat content creators as interchangeable much like TikTok. They saw the success TikTok had, tried to replicate it with Shorts and now YouTube long form is getting affected as well. I fear that in the future, uploading to YouTube will look no different than making posts on Reddit. You might get views, you might get comments, but they’re self contained to a specific post with no following building up and no guarantee of your next posts having the same reach.

Conclusion

The conclusion to all of this is that it’s not worth it to be a YouTuber. Relying on YouTube adsense and sponsorships (sponsors use views as a metric to determine how much to pay you) for your livelihood is simply not sustainable due to how fickle getting views on the platform is. Therefore, focusing so much on making YouTube content will most likely lead to your exploitation.

That said, is quitting really the answer? Considering that YouTube can give you incredible reach even if you’re a nobody as long as you make content that is remarkable, engaging (for example, through storytelling) and long enough, it would be stupid to completely walk away, at least in my case.

A New Hope

Therefore a new strategy appears on the horizon. It consists in building your audience outside of YouTube through a mailling list (Substack conveniently allows you to do so) and to strategically make occasional compelling YouTube content to tap into the platform’s reach potential. However, the key is to always direct viewers to the mailling list.

Why is building an audience through email so important? because it allows you to have a direct and long lasting link with your audience. It also gives you independence from social media platforms. Even in the case of Substack, where this article is currently hosted, I can export my email list and move to another platform or email sending service without my subscribers even noticing.

This shift implies that I no longer need to worry about pumping frequent content for YouTube because I’m not making money through them or worrying about doing so. By making YouTube content rarely, I get to keep most of my energy to build something compelling outside the platform like an actual game, writing interesting articles, making an in-depth course or other kinds of art/products.

This plan seems to me as more sustainable and more healthy long term. That’s about all I’ve got to share. Hope this article was insightful. If you’re curious to see where this journey will lead, I recommend subscribing! I usually write about programming, game development and game design.

Subscribe now

You can check some of my previous articles below.

However, while remaking it, I took a few design decisions that altered massively the replayability of the game. I’d like to share what I did.

First, I structured the game into configuration of enemies (I’ll start using the term level rather than configuration to make things clearer) that determined what enemy types and how many where to be placed on the grid. I then, tied those levels to specific score thresholds. Therefore, once a player reached a threshold they would be seamlessly moved to the next level.

Secondly, I turned the player’s score into a currency. When they had a game over, they could spend the wealth accumulated to unlock more valuable crops that would start spawning in their next attempt. Even though players always replayed the game starting from the first level, they could accumulate wealth much faster which translated to faster progress through levels they had previously played. Additionally, the more crops they unlocked, the more likely they were to reach late game levels locked behind higher score thresholds because they simply earned more.

Now, why does this structure seemingly works in making an arcade/linear game more replayable? I have a few hypothesis to present which are listed below.

1. There is now a sense of permanent progression which mitigates the feeling of loss you experience after losing in a score based game. This makes you more likely to try again.

2. Replaying previous levels while being more powerful/quicker gives the player a very satisfying feeling of power which feeds into an innate power fantasy of some sort.

3. If your game has upgrades that meaningfully alter the gameplay experience, then you tap into a novelty effect that will make the game more enjoyable for longer. For example, having unique items/weapons the player can unlock or alternative pathways in a level or an alternative level.

Isn’t this just a Roguelike Structure?

I don’t think so. Roguelikes usually rely on procedural generation and randomization to keep things fresh. There is less emphasis on level design and more emphasis on making builds and testing them out. Rather, I would estimate this structure to be more similar to time loop based games like The Legend of Zelda Majora’s Mask.

In Majora’s Mask, you play through the same handcrafted environment over and over and progressively unlock things in the game allowing you to access things you couldn’t before.

However, that doesn’t mean procedural generation can’t be used. In fact, I used it in my game, but I don’t believe in it being a core aspect.

Conclusion

Considering I accidently discovered this through experimentation, I still think there is room for fine tuning. However, this makes me excited to test this structure again in future projects. I wonder how this would fit with an RPG or a platformer, etc…

That said, it would be nice if I could get your feedback on my game. To make things as convenient as possible, here is a google form (link to the game is inside the form) for you to provide your feedback so you don’t have to create an account to be able to comment.

Anyway, if you’re interested in all things related to programming, game development and game design I recommend subscribing to not miss out on future posts.

Subscribe now

I’ve been checking out PICO-8 recently. For those unaware, It’s a nicely constrained environment for making small games in Lua. It provides a built-in editor allowing you to write code, make sprites, make tile maps and make sounds. This makes it ideal to prototype game ideas or make small games.

You know what tool is also great for prototyping game ideas or making small games? Well… KAPLAY!

It’s a simple free and open source library for making games in JavaScript. I suspect there might be a sizeable overlap between people who like PICO-8 and those who would end up liking or even loving KAPLAY as well if they gave it a try.

During my PICO-8 learning journey, I came across this nice tutorial teaching you how to make a coin collecting game in 10 minutes.

In this article, I’d like to teach you how to build roughly the same game in KAPLAY. This will better demonstrate in what ways this game library makes game development faster much like PICO-8.

Feel free to follow along if you wish to!

Installation Process

KAPLAY lacks all of the tools included in PICO-8. There is no all-in-one package you can use to write your code, make your sprites, build your maps or even make sounds.

You might be wondering, then, how KAPLAY is in any way similar to PICO-8 if it lacks all of this?

My answer : KAPLAY makes up for it by making the coding part really easy by offering you a lot logic built-in. For example, it handles collisions, physics, scene management, animations etc… for you. You’ll see some of this in action when we arrive at the part where we write the game’s code.

Now, how do we use KAPLAY? Here’s the simplest way I’ve found.

You install VSCode (a popular code editor) along with the Live Server extension (can be found in the extensions marketplace within the editor). You then create a folder that you open within VSCode.

Once the folder is opened, we only need to create two files. One called index.html and the other main.js.

Your index.html file should contain the following :

<html>
  <body>
    <script src="main.js" type="module"></script>
  </body>
</html>

Since KAPLAY works on the web, it lives within a web page. index.html is that page. Then, we link our JavaScript file to it. We set the type to “module” so we can use import statements in our JS.

We then add the following :

// in main.js
import kaplay from "https://unpkg.com/kaplay@3001.0.19/dist/kaplay.mjs";

kaplay();

Voilà! We can now use the KAPLAY library. Since we installed the Live Server extension, you should now have access to a “Go Live” button at the bottom of the editor.

To actually run the game, all you have to do is click it. This will open the web page in your default browser. KAPLAY by default creates a canvas with a checkered pattern.

One thing pretty cool with this setup, is that every time you change something in your code and hit save (Ctrl+S or Cmd+S on a Mac), the web page reloads and you can see your latest changes instantly.

Making The Game

I’ve created the following spritesheet to be used in our game.

Note that since the image is transparent, the cloud to the right is not really visible. You can download the image above to follow along.

The next step is to place the image in the same folder as our HTML page and JavaScript file.

We’re now ready to make our game.

Setting Up The Canvas

// in main.js
import kaplay from "https://unpkg.com/kaplay@3001.0.19/dist/kaplay.mjs";

// kaplay will create a canvas in index.html for us
kaplay({
  width: 1000,
  height: 1000,
  letterbox: true,
});

Here we set the width and the height of our canvas. The letterbox option is used to make sure the canvas scales according to the browser window but without losing its aspect ratio.

Loading Assets

// add this below the previous code
loadSprite("spritesheet", "./spritesheet.png", {
  sliceX: 3,
  sliceY: 1,
});

We can load our spritesheet by using the loadSprite KAPLAY function. The first param is the name you want to use to refer to it elsewhere in your code. The second param is the path to get that asset. Finally, the third param is used to tell KAPLAY how to slice your image into individual frames.

Considering that in our spritesheet we have three sprites placed in a row, the sliceX property should be set to 3. Since we have only one sprite per column (because we only have one column) sliceY should be set to 1.

Setting Key Constants and Variables Needed For The Game

// add this below the previous code

const GRAVITY_VALUE = 100;
const BASKET_SPEED = 500;
let score = 0;

Setting Gravity

// add this below the previous code
setGravity(GRAVITY_VALUE);

To make the coins fall from the top, we’ll use KAPLAY’s physics system. You can set the gravity by calling KAPLAY’s setGravity function.

Making The Background Blue

// add this below the previous code
// blue rectangle serving as our background
add([rect(1000, 1000), color(0, 170, 255)]);

KAPLAY’s add function is used to create a game object by providing an array of components. These components are offered by KAPLAY and come with prebuilt functionality. The rect() component sets the graphics of the game object to be a rectangle with a width and height of 1000. On the other hand, the color component sets its color.

Creating The Basket

// add this below the previous code
const basket = add([
  sprite("spritesheet", { frame: 0 }),
  anchor("center"),
  pos(center().x, center().y + 300),
  area({ shape: new Rect(vec2(0), 100, 100) }),
  body({ isStatic: true }),
]);

The basket is a also a game object with several different components. Here is what each does :

sprite()

Sets the sprite used by the game object. The first param is for providing the name of the sprite we want to use. Since we’re using a spritesheet which contains three different sprites in the same image, we need to specify the frame to use. The basket sprite corresponds to frame 0.

anchor()

By default, game objects are positioned based on their top-left corner. However, I prefer having it centered. The anchor component is for this purpose.

pos()

pos(center().x, center().y + 300)

This component is used to set the position of the game object on the canvas. Here we also use center() which is a KAPLAY provided function that provides the coordinates of the center of the canvas.

area()

This component is used to set the hitbox of a game object. This will allow KAPLAY’s physics system to handle collisions for us. There is a debug mode you can access by pressing the f1 (fn+f1 on Mac) key which will make hitboxes visible.

area({ shape: new Rect(vec2(0), 100, 100) }) // vec2(0) is equivalent to vec2(0,0)

As for setting the shape of the hitbox, you can use the Rect class which takes 3 params. The first expects a vec2 (a data structure offered by KAPLAY used to set pair of values) describing where to place the hitbox relative to the game object. If set to 0, the hitbox will have the same position as the game object. The two params left are used to set its width and height.

body()

body({ isStatic: true })

Finally, the body component is used to make the game object susceptible to physics. If added alone, the game object will be affected by gravity. However, to prevent this, we can set the isStatic property to true. This is very useful, for example, in a platformer where platforms need to be static so they don’t fall off.

Implementing Player Controls

// add this below the previous code
onKeyDown((key) => {
  if (key === "left") basket.move(-BASKET_SPEED, 0); // .move(velX, velY)
  if (key === "right") basket.move(BASKET_SPEED, 0);
});

Here we can use the move method available on all game objects to make the basket move in the desired direction.

Spawning Coins To Collect

// add this below the previous code
loop(1, () => {
  add([
    sprite("spritesheet", { frame: 1 }),
    anchor("center"),
    area({ shape: new Rect(vec2(0), 40, 40) }),
    body(),
    pos(randi(10, 950), -50),
    offscreen({ distance: 50, destroy: true }),
    "coin",
  ]);
});

The loop function spawns a coin every second. We use the randi function to set a random X position between 10 and 950. The offscreen component is used to destroy the game object once it’s out of view. Finally a simple string “coin” is added alongside the array of components to tag the game object being created. This will allow us to determine which coin collided with the basket so we can destroy it and increase the score.

Keeping Track of The Score

// add this below the previous code
const scoreText = add([text("0"), pos(0, 0)]);

basket.onCollide("coin", (coin) => {
  destroy(coin);
  score++;
  scoreText.text = score;
});

Text can be displayed by creating a game object with the text component. To know when a coin collides with the basket, we can use its onCollide method (available by default). The first param of that method is the tag of the game object you want to check collisions with.

Since we have multiple coins using the “coin” tag, the specific coin currently colliding with the basket will be passed as a param to the collision handler. Now we can destroy the coin, increase the score and display the new score.

Adding Clouds in The Background

As mentioned earlier, KAPLAY does not have a map making tool. However, it does offer the ability to create maps using arrays of strings. For anything more complex, you should check out Tiled which is also open source and made for that purpose.

// add this below the previous code
addLevel([
  "   #  #  ", 
  " #  #   #", 
  "#  #  #  #", 
  "  # #  # #", 
  "#  #  #"], {
  tileWidth: 200,
  tileHeight: 200,
  tiles: {
    "#": () => [sprite("spritesheet", { frame: 2 })],
  },
});

Where we place the # character in the string array determines where clouds will be placed in the game.

Full Game’s Code

import kaplay from "https://unpkg.com/kaplay@3001.0.19/dist/kaplay.mjs";

kaplay({
  width: 1000,
  height: 1000,
  letterbox: true,
});

loadSprite("spritesheet", "./spritesheet.png", {
  sliceX: 3,
  sliceY: 1,
});

const GRAVITY_VALUE = 100;
const BASKET_SPEED = 500;
let score = 0;

setGravity(GRAVITY_VALUE);

// blue rectangle serving as our background
add([rect(1000, 1000), color(0, 170, 255)]);

const basket = add([
  sprite("spritesheet", { frame: 0 }),
  anchor("center"),
  pos(center().x, center().y + 300),
  area({ shape: new Rect(vec2(0), 100, 100) }),
  body({ isStatic: true }),
]);

onKeyDown((key) => {
  if (key === "left") basket.move(-BASKET_SPEED, 0);
  if (key === "right") basket.move(BASKET_SPEED, 0);
});

loop(1, () => {
  add([
    sprite("spritesheet", { frame: 1 }),
    anchor("center"),
    area({ shape: new Rect(vec2(0), 40, 40) }),
    body(),
    pos(randi(10, 950), -50),
    offscreen({ distance: 50, destroy: true }),
    "coin",
  ]);
});

const scoreText = add([text("0"), pos(0, 0)]);

basket.onCollide("coin", (coin) => {
  destroy(coin);
  score++;
  scoreText.text = score;
});

addLevel(["   #  #  ", " #  #   #", "#  #  #  #", "  # #  # #", "#  #  #"], {
  tileWidth: 200,
  tileHeight: 200,
  tiles: {
    "#": () => [sprite("spritesheet", { frame: 2 })],
  },
});

Deployment

Publishing a KAPLAY game is very simple. You compress your folder into a .zip archive and you upload it to itch.io or any other site you wish to. The game will be playable in the browser without players needing to download it.

Now, what if you’d like to make it downloadable as well? A very simple tool you can use is GemShell. It allows you to make executables for Windows/Mac/Linux in what amounts to a click.

You can use the lite version for free. If you plan on upgrading, you can use my link to get 15% off your purchase. To be transparent, this is an affliate link. If you end purchasing the tool using my link, I’ll get a cut of that sale.

Conclusion

I just scratched the surface with KAPLAY today. I hope it gave you a good idea of what it’s like to make games with it.

If you’re interested in more technical articles like this one, I recommend subscribing to not miss out on future publications.

Subscribe now

In the meantime, you can check out the following :

I went on a quest to test the 3 most popular 2D web game frameworks according to their NPM download numbers. To achieve this, I set out to build a Sonic infinite runner game in each framework. Today, I’d like to share my findings.

Below are links to playable demos along with the source code for each version of the game. I recommend browsing the code of each version to get a better feel of the differences between them.

• KAPLAY version - (live demo) - (source code)

• Phaser version - (live demo) - (source code)

• Excalibur version - (live demo) - (source code)

Note that even though KAPLAY markets itself as a library and Excalibur as a game engine they still feel like frameworks and occupy the same space as Phaser. That’s why I took the liberty to refer to them as frameworks.

I will not beat around the bush. If you want stability and performance, you should pick Phaser. That said, overall, KAPLAY is the easiest one to learn but the least scalable of the 3. This makes it a good choice to get into game development as a beginner and to prototype ideas quickly but you’ll end up facing performance issues eventually. I’d like to note that there have been recent performance improvements. However, KAPLAY’s performance still doesn’t come anywhere close to the one offered by Phaser.

Additionally, Phaser has an AI advantage. For example, if you ask ChatGPT a question related to Phaser, more likely than not, the answer provided will be right. As for KAPLAY and Excalibur, you’ll get a lot more hallucinations. This AI advantage lowers the barrier of learning for Phaser which, in contrast, makes the easiness of KAPLAY less compelling.

While Phaser’s API is verbose, you get over it especially when you get performance and stability in exchange. Finally, Phaser is significantly more popular than the other 2 which means it will be easier to find help when needed.

If you’re looking to target mobile, Phaser is also your best bet between the 3 as the performance on Safari is also quite good and the best. This is relevant because Safari uses the Webkit web engine which is what’s forced on every browser and webview on iOS.

Finally, for multiplayer games, Phaser offers the ability to run it on the server in headless mode. This makes it much easier to handle state in a multiplayer game. To my knowledge, neither KAPLAY nor Excalibur offers something like this.

Should You Still Use KAPLAY?

As mentioned previously, KAPLAY might still be worth using in the context of prototyping or for game jams, as its component based approach allows you to truly iterate quickly on game design. Its simplicity also makes it an ideal candidate for teaching game development to beginners. Some have used it to teach children.

Should You Stil Use Excalibur?

Phaser and Excalibur felt very similar when using them as they both relied on the object oriented paradigm. Yet, I felt that Excalibur sometimes required more work. A notable example of this is when coming back to a scene after having switched away from it. The state of that scene would be left as is before transitioning over. This meant you had to write extra logic to reset the scene’s state, something you didn’t have to do in Phaser.

That said, I still felt that Excalibur’s API was on average a bit more concise than Phaser’s.

In conclusion, the issue with Excalibur is that it didn’t feel different enough from Phaser to warrant switching over to it, considering Phaser is more performant, more featureful, and more popular.

At the same time, I was impressed with how Excalibur handled its debug mode. Instead of having it within the framework, it was instead available as a browser extension. Debug mode would therefore appear in the browser devtools and could be toggled and configured from there. It was a nice experience.

GemShell

Regardless of the web framework you end up using, if you want to bring your web game to Steam, the easiest tool for achieving this is GemShell.

It allows you to create executables for Windows, Mac and Linux in what amounts to a single click. It also offers an integration with Steam so you can easily have access to features like Steam achievements and now also the Steam overlay. (The latter might not be available yet at the time of publishing this post.)

(Video by the developer showcasing the use of Steam overlay on top of a game packaged with GemShell)

This tool will save you hours that would have been wasted configuring tools like Electron and Steamworks.js. Time which could have been spent working on your game instead.

To have a consistent experience across operating systems, GemShell now makes each executable Chromium based so that your game renders the same way on all platforms.

Additionally, The developer is also considering implementing the ability to export for mobile platforms as well.

Due to how useful this tool is, I have decided to partner with its developer to offer you a 15% discount if you use the following link : https://l0om.itch.io/jslegend

To be completely transparent, if you end up purchasing GemShell using the link above, I’ll get a cut of that sale. That said, a free lite version is available, if you want to get a feel for the tool.

I hope you enjoyed this post, I recommend subscribing to not miss out on future releases.

Subscribe now

In the meantime, you can read the following :

I recently realized that if it weren’t for the fact that making games for the web was possible, I would have probably never tried game development and stuck with it. While reflecting why this was the case, I came to the conclusion that there are certain characteristics about the web that makes it an ideal platform for beginners and more experienced game developers. That’s why I’d like to convince you to start making web games if you’re not doing so already.

Limitations That Prevents Over-Scoping

A prevalent issue that occurs to most game devs is over-scoping. I recently came across a game dev youtuber who struggled to finish anything and jumped from one incomplete project to another. They were an Unreal Engine solo dev and it was clear that the projects they wanted to make were just too ambitious.

When making games for the web, you’re pretty limited in what you can do graphics wise and even scope wise (assuming you don’t make a browser based MMO that relies on a server).

For example, as long as you don’t rely on a server, a web game will usually save its data in the player’s browser local storage which gets cleared after a week or so of inactivity or when the browser cache is cleared by the user. Because of this, you’ll rarely, if ever, see someone making a game with above a couple of hours of playtime because they know they can’t rely on save data being reliably accessible. This dramatically reduces the scope expected of a web game.

No Pressure in Terms of Playtime

The fact that web games are mostly short experiences is freeing. You don’t have to worry that players will complain due to a lack of content and therefore, feel pressured to inflate the playtime.

With this worry out of the way, you can quickly go from game idea to a completed project and move on to the next idea before you even have the chance to get bored of your previous one. Due to the small scale nature of web games, you can explore different genres easily before finding what you truly like making or what garners the most attention.

This quick iteration possible with web games has a lot of similarities with making YouTube videos. You make a video, you upload it, check its stats, work on the next one where you can improve or try something different.

If you use itch.io to host your games, you get basically the same experience, you get stats where you can see how many views your game has, how many browser plays, if there are any comments, ratings, etc…

Therefore, you get a fast feedback loop which is incredibly motivating as a beginner. You can quickly incorporate improvements in your next projects. Having access to statistics allows you to know if you’re moving in the right direction.

Reaching Players is Ridiculously Easy Even Without an Audience

You might be wondering, how do you get feedback on web games if there are no algorithms like on YouTube to serve your game to a new audience? What if you don’t have a preexisting audience?

It’s true that if you publish your game on itch.io outside of participating in a game jam, you’ll be launching to crickets.

That said, I’d like to make the point that reaching players with a web game is still ridiculously easy even if you don’t have an audience. Let’s explore a few avenues you can try.

Newgrounds

Publishing your game on Newgrounds is an almost guaranteed way to get at least a few players. This is because, when publishing your game on this platform, it has to go through a rating process where the site puts your game in front of real users. After the rating process is done, you’ll get a score on 5 and a few comments. From there your game can either become more popular or stay as is.

Hacker News

While this is a tech forum, people do share games on there from time to time and they do end up on the front page. Usually, people there are technical so if you can also mention how your game was built, you might get more attention. For example, mentioning the programming language, framework, engine, etc… in the title of the post. That said, this is not strictly necessary.

When a link gets popular on Hacker News, you’ll often start seeing it shared elsewhere on your behalf, for example on Reddit, on X/Twitter, etc… this can transform into a snowball effect and make your game viral.

Reddit

It offers a dedicated subreddit for webgames like /r/WebGames where you can post a link to your game. However, try looking beyond that. For example, you can submit your game to /r/CozyGamers if you’re making a cozy game as long you follow the rules.

YouTube/Other Social Media

There is also nothing preventing you from using YouTube and other social media platforms to promote your game. Making devlogs or videos showcasing your game and putting the link to play it in the description is a great way to find new players. That said, at this point, you’re building an audience.

It might take a while to get traction but because these platforms have recommendation algorithms, at some point, some people will come across your game.

The Key : Make Remarkable Games

As with your standard PC game, the success you’ll see using the avenues I just listed depends highly on how remarkable your game is.

The strength of web games is that if you don’t see traction with one project you can quickly spin up a new one and the time you invested in building one is an order of magnitude less thant what it would take to make a Steam release.

Anyway, once one of your web games goes viral, you can invest time in making an expanded version for Steam.

People are More Than Willing to Try a Web Game From an Unknown Developer VS a Downloadable One

This seems obvious. Most people don’t want to download a game from an unknown developer because the risk of getting hacked is high.

In fact, the well known game marketing expert Chriz Zukowski mentions in his post about analyzing itch.io’s traffic that people are 3 times more likely to try your game if it’s playable on the web VS having to download it.

The friction of a web game is near 0, you’ll get more people willing to try it which translates into more people giving feedback, more attention, etc… which will in turn make a beginner more encouraged to continue their game dev journey. This is also useful for more experienced developers to know which project is worth spending more time on.

The web is also not just for completed games. Let’s say you’re having trouble finishing a project, you can still publish it as cool prototype and it will garner attention if it’s good. This will in turn maybe motivate you to push through or have a better idea of what to work on next. Contrast this with making the same project available only through a download. Nobody is going to install a 15 minute game or prototype.

You Can Expand and Bring a Web Game to Steam Easily

Most people who ridicule web games, probably think of mobile-y casual games you find on web portals that are played by children during their computer lab classes. While there are games that serve this purpose, it’s a huge mistake to view them as just that. Web games can also serve as a wonderful litmus test to determine which game ideas and concepts are worth investing time into for a full release on Steam. Web games are therefore, great for validation.

Chris Zukowksi, the game marketing expert that I mentioned previously, confirmed that this strategy actually works really well. You can check out the post were he lays this out, here.

Anyway, I’d like to emphasize that if you’re using web technologies (HTML/CSS/JS) to make web games, you’re not stuck on the web. The process of bringing a web game to Steam has never been easier.

Before, you had to configure tools like Electron to build executables for Windows, Mac and Linux. A process that took time to get right. You also had to spend additional time to configure your game’s Steam integration so you could access features like Steam achievements.

However, now there is a convenient tool called GemShell that comes with a one-click export feature to build for Windows/Mac/Linux all at once on the same machine and an easy integration with Steam. I have partnered with its developer, to offer you a 15% discount if you purchase the tool using the following link : https://l0om.itch.io/jslegend.

To be completely transparent, if you end up purchasing GemShell using the link above, I’ll get a cut of that sale.

That said, you can try the lite version for free first to see if this tool suits your needs.

You Get To Build Skills Useful Outside of Game Development

If you invest time in learning web technologies to make web games, the skills you’ll acquire will expand what you can build beyond just games. You’ll be able to build unique projects that sits between game development and web development.

The most prominent example of this, are the kind of projects you can find on the famous neal.fun website.

According to what I’ve found online, Neal uses the Vue.js JavaScript framework to build his unique games and interactive sites that go regularly viral online.

For example, one of Neal’s project is a website in which you must prove you’re not a robot by completing a series of CAPTCHA mini games.

Finally, nothing prevents you from using your web skills to build apps or game dev tools that can be easily shared with others.

Conclusion

To conclude, making games for the web is an ideal way to get into and stick with game development because of the platform’s natural constraints which encourage small finishable projects allowing the developer room for experimentation.

Since web games don’t require a download to try them, this makes it far easier to get your games in front of players even with no prior audience by sharing them on various platforms like Newgrounds, Hacker News, Reddit, etc... Therefore, you have a quick feedback loop through views, comments, ratings allowing you to remain motivated to continue your game dev journey.

Finally, successful web games can serve as validation and be expanded into a full Steam releases.

I hope you enjoyed this post, I recommend subscribing to not miss out on future releases.

Subscribe now

In the meantime, you can read the following :

Phaser is the most popular JavaScript/TypeScript framework for making 2D games. It’s performant, and popular games like Vampire Survivors and PokéRogue were made with it.

Because it’s a web-native framework, games made with Phaser are lightweight and generally load and run better on the web than the web exports produced by major game engines.

For that reason, if you’re looking to make 2D web games, Phaser is a great addition to your toolbelt.

In this post, I’ll explain the framework’s core concepts in around 5 minutes.

— SPONSORED SEGMENT —

In case you want to bring your web game to desktop platforms, today’s sponsor GemShell, allows you to build executables for Windows/Mac/Linux in what amounts to a click. It also makes Steam integration easy.

For more info, visit 👉 https://l0om.itch.io/gemshell

You have a tool/product you want featured in a sponsored segment? Contact me at jslegend@protonmail.com

The Phaser Config

A Phaser project starts with defining a config to describe how the game’s canvas should be initialized.

import Phaser from "phaser";

const config = {
  width: 1920,
  height: 1080,
  backgroundColor: "#000000",
  parent: "game", // id of the parent element of our canvas
};

new Phaser.Game(config);

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>my-phaser-game</title>
  </head>
  <body>
    <!-- canvas will be created within div with id "game" -->
    <div id="game"></div>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

To make the game scale according to the window’s size, we can set the scale property in our config.

import Phaser from "phaser";

const config = {
  width: 1920,
  height: 1080,
  backgroundColor: "#000000",
  scale: {
    mode: Phaser.Scale.FIT,
    autoCenter: Phaser.Scale.CENTER_BOTH,
  },
  parent: "game",
};

new Phaser.Game(config);

The mode property is set to FIT, so the canvas scales while preserving its own aspect ratio. As for keeping the canvas centered on the page, the autoCenter property is used with the CENTER_BOTH value.

Scene Creation

Most games are composed of multiple scenes and switching between them is expected during the course of gameplay.

Since Phaser uses the object oriented paradigm, a scene is created by defining a class that inherits from the Phaser.Scene class.

export default class Game extends Phaser.Scene {
  constructor() {
    super({ key: "game" });
  }

  create() {
  
  }

  update() {

  }
}

To be able to reference the scene elsewhere in our code, it’s important to give it a key. For this purpose and for being able to use the methods and properties of the parent class we need to call the super constructor and pass to it the key we want to use.

The two most important methods of a Phaser scene are the create and update methods.

The first is used for, among other things, creating game objects like text and sprites and setting things like scores. It runs once, every time the scene becomes active.

The latter which runs once per frame is, for example, used to handle movement logic.

Hooking Up a Scene to Our Game

Once a scene is created, we still need to add it to our game. This is done in the Phaser config under a property called scenes, which expects an array.

import Phaser from "phaser";
import Game from "./scenes/Game";
import GameOver from "./scenes/GameOver";

const config = {
  width: 1920,
  height: 1080,
  backgroundColor: "#000000",
  scale: {
    mode: Phaser.Scale.FIT,
    autoCenter: Phaser.Scale.CENTER_BOTH,
  },
  parent: "game",
  scene: [Game, GameOver],
};

new Phaser.Game(config);

The order of scenes in this array is important. The first element will be used as the default scene of the game.

Switching Scenes

To switch scenes, we can call the start method of the scene manager.

export default class Game extends Phaser.Scene {
  constructor() {
    super({ key: "game" });
  }

  create() {
     /* Switch over to the game over scene
      as soon as the game scene becomes active. */
     this.scene.start("gameover");
  }

  update() {

  }
}

Rendering Sprites

Before we can render sprites, we need to load them. For this purpose, a Phaser scene has access to the preload method where asset loading logic should be placed. To load an image, we can use the image method of the loader plugin.

export default class Game extends Phaser.Scene {
  constructor() {
    super({ key: "game" });
  }

  preload() {
      // first param is the key, second param is the path.
      this.load.image("player", "./player.png");
  }

  create() {
      this.player = this.add.sprite(500, 500, "player");
      this.player.speed = 0.02;
  }

  update(_, deltaTime) {
      this.player.x -= this.player.speed * deltaTime;
  }
}

Then, in the create method, we can render a sprite by calling the sprite method of the Game Object Factory plugin.

this.player = this.add.sprite(500, 500, "player");

The first two params are for specifying the X and Y coordinates while the third param is for providing the key of the sprite to render.

create() {
    this.player = this.add.sprite(500, 500, "player");
    this.player.speed = 0.02; // created a speed property
}

update(_, deltaTime) {
    this.player.x -= this.player.speed * deltaTime;
}

Because we created our sprite game object in the create method, we don’t have access to it in our update method, that’s why you’ll often see the pattern of assigning a game object to an instance field so it becomes accessible to other methods of the scene.

Finally, movement logic code is placed in the update method which runs every frame.

update(_, deltaTime) {
    // deltaTime is used to make movement logic frame rate independent.
    this.player.x -= this.player.speed * deltaTime;
}

Rendering Text

Rendering text is similar to sprites. Rather than the using the sprite method, we use the text method.

export default class Game extends Phaser.Scene {
  constructor() {
    super({ key: "game" });
  }

  create() {
    this.add.text(100, 100, "Hello World");
    this.add.text(100, 100, "Fancier Hello World", {
      fontFamily: "Arial",
      fontSize: 32,
      resolution: 4, // Makes the text sharper. Text is a bit blurry by default. 
    });
  }
}

Entity Creation

If you want to hold data or define custom methods for a sprite game object, a better approach is to define a class that inherits from the Phaser.GameObject.Sprite class.

export default class Player extends Phaser.GameObjects.Sprite {
    constructor(scene, posX, posY, speed) {
        super(scene, posX, posY);
        this.speed = speed;
        // add the game object to the scene
        scene.add.existing(this);
    }

    // custom method.
    jump() {
        // ...
    }
}

Once the class is defined, we can use it in our scene’s code.

export default class Game extends Phaser.Scene {
  constructor() {
    super({ key: "game" });
  }

  create() {
    // ...
    this.player = new Player(this, 500, 500, 0.02);
    this.input.keyboard.on('keydown-SPACE', () => {
        this.player.jump();
    });
  }
}

Asset Loading

While asset loading can be done in any Phaser scene, a better approach is to create a scene dedicated to loading assets, which then switches to the main game scene once loading is complete. This can be achieved like shown below :

export default class Loader extends Phaser.Scene {
  constructor() {
    super({ key: "loader" });
  }
  preload() {
    this.load.spritesheet("ring", "./graphics/ring.png", {
      frameWidth: 16,
      frameHeight: 16,
    });
    this.load.image("platforms", "./graphics/platforms.png");
    this.load.audio("jump", "./sounds/Jump.wav");
  }

  // runs once loading logic is complete.
  create() {
      this.scene.start("game");
  }
}

Animation API

Another important aspect of any game is the ability to play animations. Usually for 2D games, we have spritesheets containing all the needed frames to animate a character in a single image.

In Phaser, we first specify the dimensions of a frame in the loading logic of the spritesheet so that the framework knows how to slice the image into individual frames.

preload() {
  this.load.spritesheet("dog", "./graphics/dog.png", {
    frameWidth: 32,
    frameHeight: 32,
  });
}

Then, we can create an animation by defining its starting and ending frames.

create() {
  this.anims.create({
    key: "walk",
    frames: this.anims.generateFrameNumbers("dog", {
      start: 0,
      end: 3,
    }),
    frameRate: 8,
  });
}

To provide the needed frames we call the generateFrameNumbers method of Phaser’s animation manager.

Finally once the animation is created, it can be played by using the play method of the sprite game object.

this.player = this.add.sprite(500, 500, "dog");
this.player.play({key: "walk"});

If you want the animation to loop back indefinitely, add the repeat property and set it to -1.

this.player = this.add.sprite(500, 500, "dog");
this.player.play({key: "walk", repeat: -1});

Input Handling

A game needs to be interactive to be called a “game”. One way to handle input is by using event listeners provided by Phaser. For keyboard input, we can use this.input.keyboard.on() :

create() {
  const jumpLogic = () => {
    // You jump logic
  };
  this.input.keyboard.on("keydown-SPACE", jumpLogic);
}

And for handling mouse and touch input we can use this.input.on().

create() {
  const jumpLogic = () => {
    // You jump logic
  };
  this.input.keyboard.on("keydown-SPACE", jumpLogic);
  this.input.on("pointerdown", jumpLogic);
}

Sharing Data Between Scenes

At one point, you might need to share data between scenes. For this purpose, you can use Phaser’s registry. Here is an example of its usage.

export default class Game extends Phaser.Scene {
  constructor() {
    super({ key: "game" });
  }

  create() {
    this.registry.set("score", 100);
    this.scene.start("gameover");  
  }
}

export default class GameOver extends Phaser.Scene {
  constructor() {
    super({ key: "gameover" });
  }

  create() {
    const currentScore = this.registry.get("score");
    // display the score
    this.add.text(0, 0, currentScore);
  }
}

Playing Sound

To play sounds (assuming you have already loaded the sound first) you can use the play method of the sound manager.

preload() {
   this.load.audio("jump", "./sounds/Jump.wav");
}

create() {
   this.sound.play("jump", {volume: 0.5});
}

You can specify the sound’s volume in the second param of that method.

If you need to be able to stop, pause or play the same sound at a later time, you can add it to the sound manager rather than playing it immediately.

create() {
  this.citySound = this.sound.add("city", { volume: 0.2, loop: true });
  this.citySound.play();


  // later in your code in some game over condition.
  if (this.isGameOver) {
    this.citySound.stop();
  }
}

This comes in handy when you transition from one scene to another and you have a sound that loops indefinitely. In that case, you need to stop the sound before switching over otherwise the sound will keep playing in the next scene.

Physics, Debug Mode, Physics Bodies and Collision Logic

By default, Phaser offers an Arcade physics system which is not meant for complex physics simulations. However, it’s well suited for most types of games.

To enable it, you can add the following to your Phaser config.

const config = {
  //... omitted for clarity
  physics: {
    default: "arcade",
    arcade: {
      gravity: { y: 4000 },
      debug: false,
    },
  },
};

new Phaser.Game(config);

You can add an existing game object to the physics system the same way you add one to a scene.

export default class Player extends Phaser.GameObjects.Sprite {
  constructor(scene, x, y) {
    super(scene, x, y);
    scene.add.existing(this);
    scene.physics.add.existing(this); // <--
    this.body.setSize(22, 26);
  }
  // ...
}

This will create a physics body for that game object which is accessible with the body instance field. You can view this body as a hitbox around your sprite if you turn on the debug mode in your project’s config.

const config = {
  //... omitted for clarity
  physics: {
    default: "arcade",
    arcade: {
      gravity: { y: 4000 },
      debug: true, // <--
    },
  },
};

new Phaser.Game(config);

To create bodies that aren’t affected by gravity, like platforms, you can create a static group and then create and add static bodies to that group. Here’s an example :

// For example, in the create method of the Game scene
create() {
  const groundGroup = this.physics.add.staticGroup();
  this.ground = groundGroup.create(960, 920); // Create a single static body. Call this multiple times to create more.
  this.ground.setSize(1920, 160);
}

You can also add already existing physics bodies to a group.

create() {
  this.enemies = this.add.group();
  // assuming you have defined an Enemy class similarly to the one shown previously for the player.
  this.enemies.add(new Enemy(this, 100, 100))
}

Now, you might be wondering what groups are useful for? They shine in collision handling logic.

Let’s assume you have multiple enemies attacking the player. To determine when a collision occurs between any enemy and the player, you can set up the following collision handler :

create() {
  this.physics.add.collider(this.player, this.enemies, (_, enemy) => {
    // enemy is the specific enemy of the enemies group colliding with the player.
    console.log(enemy);
  });
}

Project Based Tutorial

There are many concepts I did not have time to cover. If you want to delve further into Phaser, I have a project based course where I guide you through the process of building a Sonic themed infinite runner game.

This is a great opportunity to put in practice what you’ve learned here. If you’re interested, you can watch it here :

Conclusion

If you enjoy technical posts like this one, I recommend subscribing to not miss out on future releases.

Subscribe now

In the meantime, you can read the following :

Programmers are known to not have a strong suit for art related disciplines, pixel art is no exception. In this post, I’ll share 5 tips for making good pixel art from the point of view of a programmer. This is to help other solo devs coming from a programming background to make better pixel art for their games.

Now, you might be wondering if I’m qualified to share tips related to pixel art? Below are two pixel art asset packs I made. If you like how they look, then the question is answered.

Here are all the asset packs I’ve made so far :

• Kirby like platformer asset pack (FREE)

• Mario-like Platformer Asset Pack ($4)

• 2D Pixel Art Samurai Arena ($4)

Additionally, I’m making all the art for a small RPG I’m working on.

Tip #1 : Nurture Good Taste in Pixel Art

How do you know if a sprite looks good or not? You might have assumed that you just need to look at it and your brain determines whenever it’s appealing or not. Maybe the colors clash or the pixels are not placed symmetrically, etc… all things that you should detect naturally.

However, it’s not that simple, an art piece can go against commonly held rules and still look good. It can look good to one person but not to another.

While it’s true that whether a sprite or any piece of art looks good is subjective to some extent, it’s undeniable that some of them are widely considered more appealing.

This subjective nature of art is what a lot of programmers struggle with. You might be used to having a compiler compile and run your code. If your code successfully runs then you know that at least your code works.

With art however, you need to acquire good taste that will effectively act as your own internal compiler when doing pixel art. It will guide you during your art process and allow you to realize when things don’t work (ex: Color clashes, etc…).

The question now becomes, how do you develop good taste in pixel art? The simplest way is to look at well regarded pixel art online. It can come from games where the art is praised or from pixel artists online. When observing each piece, try to notice the details. If you do this enough, you’ll build an internal understanding of what makes good pixel art.

Tip #2 : Don’t Draw! Negotiate Your Pixels Instead

If you come to pixel art with the mindset that you’re going to draw what you want like you would on pen and paper, you’re going to get frustrated. Pixel art at low resolutions is all about negotiating with your canvas.

It’s basically a puzzle game. You need to figure out where to place your pixels to represent what you want while still compromising on certain details.

The sooner you view pixel art like this, the less you’re going to struggle drawing the sprites you need for your games. This is because you’re now more flexible and ready to adapt when representing certain things that are challenging at low resolutions.

Tip #3 : Reference Other Pixel Art as Much as Possible

You can either do the hard work of figuring out how to represent an object or character in lower resolutions or you can go look at the million of available game sprites that already solved what you’re trying to represent.

That’s why I recommend using references extensively.

For example, if you want to make a top-down action adventure game a la Zelda there is no shame in looking up link’s sprites to see how he’s represented or how his sword attack animations are made.

In case you didn’t know, the most comprehensive website for looking up sprites from various retro games is The Spriters Resources.

Tip #4 : Stick to a Limited Color Palette but Expand It if Needed

Sticking to a limited color palette is very important in pixel art due to the low amount of space available. Every color you choose will have a big impact on the appeal of the final sprite.

If you don’t want to deal with color theory, you can always pick an existing color palette. There is this website called Lospec with plenty of color palettes you can pick from. On this website, you can often see pixel art examples using the listed color palette. This will help you determine if a given palette will likely help you achieve your desired aesthetic.

Another option consists in finding a pixel art piece you like online and picking the same colors to make your palette.

Finally, you might feel too constrained working with a limited amount of colors. Sometimes, the colors you have in your palette are not enough. In that case, I recommend adding colors to it.

In fact, it’s much easier to expand a given color palette one color at a time then to not limit yourself to one by choosing colors on the fly. When needing a new color, you can more easily compare your new color choice with an existing palette and see if it fits or change your choice otherwise.

Tip #5 : Constraints Breeds Creativity and Hides Your Flaws

I often hear the phrase “Constraints breeds creativity” and I agree because when constrained you often end up finding creative solutions. However, another lesser known benefit of constraints is that they allow you to hide your flaws.

The less constraints you have, the more ambitious you get, the higher the likelihood of going out of your comfort zone and finding yourself in an area where you do not have enough skill to pass the “professional” quality bar.

For example, if you’re someone with very limited coloring skills. I would recommend sticking to a predefined color palette of max 4 colors. This way, you can more easily reach a “professional” looking result compared to if you had to pick your own colors.

Well chosen constraints allows you to put forward your strengths while hiding your flaws. Another way to put it would be that constraints reduces the likelihood of shooting yourself in the foot.

Conclusion

While I hope these tips will help you make better pixel art, it’s no secret that practice remains a big part of what you need to do to achieve good results.

If you’re interested in reading more posts like this. I recommend subscribing to my Substack as to not miss out on future releases.

Subscribe now

In the meantime, you can check out my previous posts.

I recently discovered that you could make PS2 games in JavaScript. I’m not even kidding, it’s actually possible. I was working on a project and had my phone near my desk when I received a notification. Upon further inspection, it came from itch.io which was a platform where I usually published most of my web games.

Under my relatively popular Sonic infinite runner game which was made in JavaScript and developed a year ago, I received a comment from someone with the username Dev Will which claimed they had made a PS2 version of my game and provided the GitHub repo of the source code.

At first, I thought that it was cool that someone took the time to remake my game for an old console that had a reputation to be hard to develop for and probably required them to write a lot of C or C++.

Out of curiosity, I opened up the GitHub repo and was astonished to see that the project was not using even a bit of C++ or C but was entirely in JavaScript!

If making PS2 games were easier than I thought since I could use a higher level language like JavaScript, I could probably try making one in a reasonable amount of time and play it on a retro handled or an actual PS2. How cool would that be?

This is where I knew I had to drop everything I was doing to investigate how this was possible.

The AthenaEnv Project

Since the dev behind the project was Portuguese speaking (I assume they were either from Brazil or Portugal), they wrote the Readme of the repo in Portuguese which was a language I did not understand.

Fortunately, I was still able to decipher most of what was written because I had done 3 years of Spanish in school and spoke French natively. Since Portuguese is a romance language like Spanish and French, I was fortunately not totally lost.

Anyway, The readme said that the engine used to make the PS2 version of my game was called AthenaEnv with a conveniently placed link towards it so I could learn more.

As with the Sonic Infinite Runner PS2 project, this engine was also open source and its repo had a very detailed readme written in English.

To summarize, Athena was not what we commonly refer to as a game engine but an environment that also offered a JavaScript API for making games and apps for the PS2. It embedded a slightly modified version of QuickJS which was a small and embeddable JavaScript engine. This explained how Athena was able to run JavaScript code on the PS2.

Therefore, Athena was the PS2 native program written in C that took your JavaScript code, passed it through the QuickJS engine to interpret it and finally, ran the relevant logic on the system.

What made it compelling was not that it just ran JS on the PS2 but that it offered an API suitable for game development. It covered :

• Rendering : Allowing you to display sprites, text, shapes, etc… on the screen and animate them using a game loop.

• Asset loading : Allowing you to load images, sounds, fonts, etc...

• Input handling : Allowing you to receive player input from a controller, multiple ones or even from a mouse and keyboard since the PS2 supported these input methods.

• File handling : Allowing you to write save files among other things.

• Sound playback : For playing Sound.

and the list goes on.

I noticed however, that the level of abstraction offered by the API was similar to something like p5.js, the HTML canvas API or Raylib. That meant that you’d still needed to implement collision detection, scene management, etc… yourself.

Now, that I got familiar with Athena, I wanted to try to run the Sonic infinite runner “port” on an emulator. According to the project’s Readme. I needed to install PCSX2 which is the most popular emulator for the PS2. Then, go into the settings and under the emulation tab, check the box “Enable host filesystem”.

Once this was done, I would need to open an athena.elf file and the game would start.

After installing and configuring the emulator, I was ready to run the game. However, there was a problem. I could not find the athena.elf file in the repo. It was nowhere to be found.

This is where I remembered to look at the “releases” section of the repo because a lot of open source projects put executables there, especially if it’s a mobile or desktop app project.

As expected, the zip attached in that section contained the athena.elf file but not only. It also contained an assets folder, a main.js file, an athena.ini file and src folder containing the rest of the game’s code.

The athena.ini file allowed you to configure the entry point of the project. Here, the entry point was set to main.js which explained how Athena would know what JavaScript to run. You could also configure if you wanted to show Athena’s logo before your game started by setting the boot_logo property to true.

boot_logo = true
dark_mode = true
default_script = “main.js”

audsrv = true

It now became evident why we needed to check the “Enable host filesystem” check box earlier. This was so that the emulator could allow Athena to access the assets folder and the source code that were essential for our game.

Anyway, I opened the athena.elf file in PCSX2 and surprisingly, the game actually ran with no issues. It was amazing to see that a game I wrote for the web was ported to the PS2 and I was there able to play it with a controller.

Now, the game looked a bit blurry which was expected since this was supposed to emulate a PS2 which had a small resolution. Fortunately, I was able to make things more comfortable by upping the resolution in the graphics settings of the emulator.

The dev process also seemed quite straightforward. You would only need to open the folder containing all the relevant files (athena.elf, main.js, etc…) in a code editor like VSCode and open athena.elf in the emulator. Now, you could make changes to your JS code and once you were ready to test, you would go under the PCSX2 system tab and click on reset. This would restart the emulator and you could see the latest changes. While not as seamless as in web development with hot reloading, it still was a relatively fast iteration cycle.

It’s at that moment, that I knew had to make a post about it and share this awesome project with you. However, I still felt uneasy about one thing.

Nowadays, people download PS2 games as .iso files. For most games, you only need one .iso file that you then open in your emulator. Less technical people can therefore more easily enjoy these older titles.

However, to run the Sonic infinite runner game “port”, I needed to not only check a box in the settings but also needed the entire project’s folder containing the Athena executable and the source code.

I wondered if instead, there was a way to distribute the game as a single .iso file. This is were I simply went back to the itch.io comment section and asked if it was possible.

After a thorough back and forth that continued on Discord, the process to convert my files into a single iso, I could distribute, was now clear.

Making an .iso File

To make an iso you needed the following files :

• athena.elf : Which is the Athena executable.

• athena.ini : For configuring the project’s entry point.

• A JS file acting as the entry point of the codebase.

• The rest of your source code if your code is more than one file, oftentimes it’s in a folder called src.

• Two files one named ATHA_000.01 and the other SYSTEM.CNF needed to make the iso bootable.

As an aside, in case you want to also get into JavaScript PS2 game development, you can check this template I made containing all of the files needed.

Once you had all the files, you had to make a zip archive containing them all. One issue I had, was that if I created a zip out of the folder containing the files, the resulting .iso would not work. However, if I selected the files one by one and then created the zip, I would experience no issues. This is something to keep in mind.

Now, the only step left was to convert the zip into an iso. As I was using a Mac, the only reliable way I’ve found, was to use the website mconverter.eu and let them do the conversion.

However, the issue with this website is that you’re limited in the number of conversions you can do per day before they ask you to pay. Additionally, if your zip archive is above a certain size, you’ll also have to watch an ad before you can do the conversion.

If you end up finding a better way using either a CLI tool, a downloadable app or some other website, feel free to share it in the comment section.

Once you had the iso, you could open it up in the emulator like you would do with other PS2 games. You also didn’t need to check the “Enable host filesystem” option anymore since all the relevant files needed were included in the iso.

If the game booted correctly, then you now had a single file you could distribute which was very convenient.

Hello World Example

It was now time to get my feet wet. Before attempting anything too complicated, my goal was to create a simple “Hello World” example where I would :

• Load some assets (In my case a font and an image).

• Set up a game loop that would run every frame.

• Animate a sprite using that game loop.

• Render text.

• Handle player input so I could move a sprite around.

Setup

Before I could achieve any of these sub-goals, in main.js, I first defined a few constants that I would end up needing.

const { width: SCREEN_WIDTH, height: SCREEN_HEIGHT } = Screen.getMode();
const SCALE = 2;
const SPEED = 3;
const FRAME_WIDTH = 32;
const FRAME_HEIGHT = 44;

This is where I learned that you could get the screen’s width and height by first using the Screen module available globally like all Athena provided modules (Meaning that no import statements were needed) and then calling the getMode method.

Then, to have a stable frame rate and accurate FPS counting, I needed to call the methods setVSync() and setFrameCounter()

Screen.setVSync(true); // makes framerate stable
Screen.setFrameCounter(true); // toggles frame counting and FPS collecting.

Loading Assets

With the setup completed, I wanted to load the font I used in my Sonic game and a Spritesheet of Sonic so that I could later animate it. I could achieve the following by creating an instance of the Font and Image classes offered by Athena.

const maniaFont = new Font("./assets/mania.ttf");
const sprite = new Image("./assets/sonic.png");

Setting Up Player Input

While I planned on handling player input later, I still needed a way to get the player’s controller so that my code could know when a given button was pressed. This was made possible by using Athena’s Pads module.

// Get the first player controller
// First player -> 0, Second player -> 1
const pad = Pads.get(0);

Setting Up Animation Logic

Before I could create a game loop, I needed to first write the setup code required to animate my spritesheet. Since all the frames where contained within a single image, I had to find a way to tell Athena what part of the image was to be rendered.

To achieve this, I first spent some time to get familiar with the shape of the sprite object created earlier.

const sprite = new Image("./assets/sonic.png");

It turned out that we could set the width and the height of the sprite by modifying the properties of the object with the same names.

// for example
sprite.width = 30;
sprite.height = 40;

It also turned out that you could tell Athena what portion of the image to draw by setting the startx, endx, starty, endy properties.

sprite.startx = 0;
sprite.endx = 32;
sprite.starty = 0;
sprite.endy = 44;

For example, if you had the following values : startx = 0, endx = 32, starty = 0 and endy = 44 you would get the first frame rendered. This is because in the spritesheet, every frame has a width of 32 and a height of 44. Also, the origin (0,0) corresponds to the top-left corner of the spritesheet.

Now that I knew how to display a single frame within a wider image, I used the following logic to setup Sonic’s run animation.

const spritePos = { x: SCREEN_WIDTH / 2, y: SCREEN_HEIGHT / 2 };
sprite.width = FRAME_WIDTH * SCALE;
sprite.height = FRAME_HEIGHT * SCALE;
// describes where each frame is located within the sprite.
const runAnimFrames = [
  { startx: 0, endx: 32, starty: 0, endy: 44 },
  { startx: 32, endx: 64, starty: 0, endy: 44 },
  { startx: 64, endx: 96, starty: 0, endy: 44 },
  { startx: 96, endx: 128, starty: 0, endy: 44 },
  { startx: 128, endx: 160, starty: 0, endy: 44 },
  { startx: 160, endx: 192, starty: 0, endy: 44 },
  { startx: 192, endx: 224, starty: 0, endy: 44 },
  { startx: 224, endx: 256, starty: 0, endy: 44 },
];
let frameIndex = 0;
const frameDuration = 30;
const timer = new Timer();

I first created an object called spritePos to set the position of the sprite on the screen. This was needed to be able to move it around when the player would press directional buttons on the D-pad. More on that later.

Then I would set the sprite’s width and height to correspond to the width and height of a single frame which was 32x44 pixels. Since I wanted the sprite to appear big enough, I multiplied the width and height by a value defined by the SCALE constant we set earlier in our code.

The next step consisted in creating an array called runAnimFrames which would describe each frame of Sonic’s run animation using an object with the startx, endx, starty and endy properties. We then had a frameIndex variable which would determine the current frame to display. The frameDuration constant would be used to set how long in miliseconds to display each frame. The lower the number the higher the frame rate of the animation because we would flip through all the frames faster.

Finally, I initialized a timer coming from a custom Timer class that I added in my src folder and imported here. The full code is available in the template mentioned earlier.

The timer would end up being crucial to know when it was time to move on to displaying another frame.

Creating our Game Loop

Now that we had our animation logic setup done, it was time to render the animation. For this purpose, I needed a game loop that runs every frame. In Athena, we could achieve this by calling the display method available under the Screen module.

Screen.display(() => {
   if (timer.get() > frameDuration) {
      if (frameIndex < runAnimFrames.length - 1) {
          frameIndex++;
          timer.reset();
      } else {
          frameIndex = 0;
      }
   }

   sprite.startx = runAnimFrames[frameIndex].startx;
   sprite.endx = runAnimFrames[frameIndex].endx;
   sprite.starty = runAnimFrames[frameIndex].starty;
   sprite.endy = runAnimFrames[frameIndex].endy;
   sprite.draw(spritePos.x, spritePos.y);
});

In an if statement we would check if the timer had exceeded the time allocated to displaying the current frame. If it was the case we would move on to the next frame by incrementing the frameIndex as long as it was within the bounds of the runAnimFrames array, otherwise, we would set it back to 0 to display the first frame. This was to achieve a looping animation.

Then, on every iteration of the game loop we would set the sprite’s startx, endx, starty, endy properties to correspond to the ones of the current frame. Finally, to render the sprite, we needed to call its draw method and pass to it the coordinates where you wanted to display it on the screen.

Handling Player Input

Now that I had a game loop, I could finally handle user input by making sure that the sprite would move in different directions depending on which button was pressed. This could be easily achieved with a few if statements.

Screen.display(() => {
   pad.update(); // necessary to get what buttons are currently being pressed

   if (pad.pressed(Pads.RIGHT)) {
       spritePos.x = spritePos.x + SPEED;
   }

   if (pad.pressed(Pads.LEFT)) {
       spritePos.x = spritePos.x - SPEED;
   }

   if (pad.pressed(Pads.UP)) {
       spritePos.y = spritePos.y - SPEED;
   }

   if (pad.pressed(Pads.DOWN)) {
      spritePos.y = spritePos
   }

   // rest of the code omitted for clarity
});

You might be wondering where is deltaTime? For those unfamiliar, deltaTime is a value representing the time elapsed between the current frame and the previous frame in a game. It’s often used to make the movement of objects, frame rate independent. Meaning that if your game runs at a lower or higher frame rate, an object, like a character, will still move at the same rate. To achieve frame rate independence, you would usually multiply your movement code by deltaTime.

The reason it was absent here, is because when creating a game loop using the display method, this matter is taken care of under the hood.

Mirroring a Sprite

Now that I could move Sonic around, I still needed him to face the correct direction because at this point, he would look right even If I moved him to the left. To implement this, I decided to go with a common technique in pixel art based games, which consisted in mirroring (or flipping) the sprite.

To achieve this in Athena, you simply needed to provide a negative width or height to the sprite depending on what axis you wanted the mirroring to take effect on. For flipping a sprite horizontally, providing a negative width was enough.

However, an issue arose! If you flipped the sprite, it would not flip in place since it would flip according to the sprite’s origin which was its top-left corner.

This meant that it would move the sprite to the left after mirroring. To fix this issue, you only needed to subtract an offset to the x coordinate of the flipped sprite that corresponded to its width.

Now that the issue was solved, I created variable called spriteIsFlippedX to know when to flip or unflip the sprite. The logic can be see below :

// omitted previous code for clarity
const offset = FRAME_WIDTH * SCALE;
let spriteIsFlippedX = false;

Screen.display(() => {

  pad.update();

  if (pad.pressed(Pads.RIGHT)) {
    // makes sur to flip back the sprite
    if (spriteIsFlippedX) {
      sprite.width = Math.abs(sprite.width);
      spriteIsFlippedX = false;
      spritePos.x -= offset;
    }

    spritePos.x = spritePos.x + SPEED;
  }

  if (pad.pressed(Pads.LEFT)) {
    if (!spriteIsFlippedX) {
      sprite.width = -Math.abs(sprite.width);
      spriteIsFlippedX = true;
      spritePos.x += offset;
    }

    spritePos.x = spritePos.x - SPEED;
  }

  if (pad.pressed(Pads.UP)) {
    spritePos.y = spritePos.y - SPEED;
  }

  if (pad.pressed(Pads.DOWN)) {
    spritePos.y = spritePos.y + SPEED;
  }

  // ... code omitted for clarity
});

Now, when you moved sonic to the left, he would face left and face right when moved to the right.

Rendering Text

There was still one thing I wanted to try out before wrapping up my Hello World example and that was text rendering. The first thing I wanted to render onto the screen was an FPS counter. It turned out that the FPS counter in the PCSX2 emulator is not accurate, however, Athena provides the getFPS() method available on the Screen module to accurately determine the frame rate.

To display some text, you needed to first create a font object using the Font constructor. It would take either a path to a font that can be in a .ttf format or the string “default” if you wanted to use the default font available on the system.

Once created, the font object had a print method that you could use within the game loop to tell the PS2 what to render and where on the screen.

const font = new Font("default");
Screen.display(() => {
    // Here getFPS() will provide an updated FPS count every 10ms.
    font.print(10,10, Math.round(Screen.getFPS(10)));
});

const maniaFont = new Font("./assets/mania.ttf");
Screen.display(() => {
    font.print(10,10, "Hello World!");
});

Finally, my Hello World example was finished.

Now that you’ve been introduced to Athena, you might be tempted to try it out for yourself. In that case, I really recommend looking at the Sonic infinite runner Athena port’s code as you’ll learn a lot about concepts that I did not have time to cover here.

Link to the repo here : https://github.com/DevWill-hub/Sonic-Infinite-Runner-PS2

Link to my Athena template : https://github.com/JSLegendDev/Athena-PS2-Template

Link to the Athena project : https://github.com/DanielSant0s/AthenaEnv

Additionally, I recommend joining the official Athena discord where you’ll be more likely to receive help when stuck. You can join here : https://discord.gg/cZUH5U93US

How About 3D?

Before wrapping up this post, you might have found strange that nothing was mentioned about 3D considering that the PS2 was mostly known for its 3D games.

This is for 2 reasons. First, I’m a novice in terms of 3D game develoment, I have never done it before. Second, to my understanding, Athena has both 2D and 3D capabilities but version 4 which has more of a 3D focus is currently in development. I thought it would have been preferable to wait until v4 was stable before diving into PS2 3D gamedev in JavaScript.

However, there are a few 3D demos you can check if you’re interested.

Links down below.

• https://github.com/ps2devnoob/3D-Robot-DEMO-PS2

• https://github.com/ps2devnoob/BurnTrack-PS2-DEMO

• https://github.com/ps2devnoob/AthenaENV-PS2-Samples

Conclusion

To conclude, Athena is a cool project allowing you to make real PS2 games in JavaScript. If you learned something new and enjoy technical posts like this one, I recommend subscribing to not miss out on future releases.

Subscribe now

In the meantime, if you feel inclined, you can read the post below.

The story of how I started game development is quite unusual, which led me to not using game engines and allowed me to get familiar with alternative tooling.

When I reached the age to go to university, I chose computer science as my major not to learn to make games but with the aim of studying AI. However, by the time I ended up graduating, my interest for AI had completely vanished. The math needed for it did not interest me.

Instead, I used to spend my time building web related projects which I then put on my resume and was able to land a job as a software developer. In that job, we used a JavaScript and TypeScript based stack.

It was during that time that I came across a nice little library called Kaboom.js. It would end up later as KAPLAY. This library would allow you to make 2D games quickly using either JavaScript or TypeScript. As someone with no real experience in game dev, this was right up my alley as I already had the prerequisites to learn this library quickly.

Considering that this was a library and not a game engine, the development setup was quite familiar with what I was used to in my day job (at the very least the frontend portion of it). You would write your code in an editor and look at the preview in your browser.

My first few games were simple, they would take place in a single scene and I would hard code the positions of game objects into my code.

As my projects got bigger, I started to use a feature provided by Kaboom.js allowing me to describe the layout of a level using an array of strings. For each character, you could tie a specific game object that would be spawned according to where the character was located in the string array.

// An example
const myLevel = add([
    level(
        [
            "         ",
            "         ",
            "  @  ^ $$",
            "  =======",
        ],
        {
            tileWidth: 64,
            tileHeight: 64,
            tiles: {
                "@": () => [
                    sprite("bean"),
                ],
                "=": () => [
                    sprite("grass"),
                ],
                $: () => [
                    sprite("coin")
                ],
                "^": () => [
                  sprite("spike")
                ],
            },
        },
    ),
]);

While this was much better than hard coding coordinates, it became tedious when I wanted to make maps with multiple layers since each layer was represented with its own array of strings. Therefore, I wouldn’t know how the map would really look like unless I ran the code. It also felt annoying to reposition objects by adding spaces in a string or removing them.

Dissatisfied with the string-based approach, I decided to search how others tackled the problem.

I first got familiar with how game engine users did things. For Unity, Godot or Unreal they were all provided a built-in editor where they could easily place objects around and run their games.

It dawned upon me why people preferred to use ready made game engines due to how convenient this was but I didn’t feel like spending the time to learn an engine just for this. However, if I couldn’t find a solution that was better then what I had, I would probably bite the bullet and start learning game dev from scratch with one of the major engines.

I then came across developers with an approach that seemed a bit crazy. They just decided to invest time in building their own tooling for map/level making. As a programmer, while I appreciate the exercise, I felt that this was not worth my time unless, I had really no options and with the goal of making an editor that was general enough that I could sell as a product to other developers.

This is where I wondered: Has no one made a general-purpose editor for map-making that can be used by anyone working with libraries and game frameworks rather than engines? This prompted me to do some research, I came across 3 options :

• Ogmo Editor

• LDTK

• Tiled

I first found out about Ogmo when I tried learning the HaxeFlixel game framework. In the official tutorial, they used Ogmo to design the tutorial game’s map. Since, I didn’t end up pursuing HaxeFlixel much further. I kind of forgot about Ogmo and moved on.

As for LDTK, it was an editor made by the developers behind the popular game Dead Cells. It looked nice, but I ended up using Tiled because it was the most popular.

According to their home page, Tiled was used to design the levels of popular indie games like Shovel Knight and Axiom Verge amongst others. However, the reason that really pushed me over to use it over other options, was the fact that someone had written a plugin to integrate maps made with Tiled with the library I was using.

Learning Tiled

At first, Tiled’s interface looked ugly and not very intuitive but ultimately the way it worked was relatively simple.

You first started by creating a map by setting the size of each tiles and its width and height.

You then, imported your tileset and finally created a first tile layer on which you could draw using tiles from that tileset.

An arbitrary number of layers could then be created to appear on top of the first one allowing you to design complex looking maps.

In the inspector, you could rename layers and change their order, which would determine the order in which they would be rendered.

In addition to being able to create tile layers, you could create a second type of layer called an object group. This layer type could be used to place collider shapes which you could use in your code to determine which parts of the map were walls.

Alternatively, you could also place pins that could be used to position players, enemies and other game objects in your map.

Finally, you would be able to export your map into various formats depending on your needs.

After having learned how to use Tiled, I had finished creating a test map and was eager to test the plugin that would allow me to render it in my game. Unfortunately, I realized that the plugin didn’t work!

I concluded that the plugin expected an older deprecated version of the library explaining why it didn’t work. Kaboom.js (now KAPLAY) also didn’t have an official way of importing maps made with Tiled and still doesn’t.

I therefore felt pretty much stuck. I tried reading the code of the plugin but didn’t understand much of it.

I was about to give up feeling frustrated of not being able to achieve my goals because the people maintaining the software I was using did not take into account my use case and why would they? They maintained the library for free. They wrote the plugin for free. It was being dependent to them that felt annoying. I did not want to wait for someone else to do the work before I could continue my projects.

I also wasn’t your average software user anymore. Software is often thought as a black box. Developers know the internals and users just use the software from the outside via an interface.

However, I had a computer science degree, I knew how to code, why should I wait and not fix my pain point myself.

That’s because jumping into a new codebase as a dev is often still intimidating. You don’t have the context that led to various decisions around the code and you need to get familiar with a lot at once which always made me wary of trying to fix things myself for open source software I was using. I really needed a good reason to justify the effort.

However, this time was different, I was motivated and didn’t even need to jump into a codebase. What I needed to do was to learn how the Tiled export file worked so I could parse it in my game code and render the map.

I was initially intimidated by the various file formats you could use as exports. However, I was relieved to discover that you could export your map as a JSON file.

For those unfamiliar, JSON is a relatively simple format composed of an object with an arbitrary amount of key value pairs where keys are called properties. It’s inspired by the way objects are created in JavaScript and that’s why it’s called JavaScript Object Notation (JSON).

It’s an incredibly common format used a lot in web development. For example, it’s often used by backends and third party APIs to send data upon being requested by frontends or users of those APIs.

Knowing that we could export the map as a JSON file allowed me to answer a big question I had in mind. How to import a map made with Tiled in my codebase?

As with regular API requests, I simply needed to use the fetch() JavaScript function to fetch the file and then convert its response using the .json() method which allowed me to load the JSON into an actual JavaScript object I could use in my code.

With this out of the way, the next step was to figure out how the export file was structured so I could know how to render the map.

// map.json
{ 
 "compressionlevel":-1,
 "height":30,
 "infinite":false,
 "layers":[...],
 "nextlayerid":6,
 "nextobjectid":71,
 "orientation":"orthogonal",
 "renderorder":"right-down",
 "tiledversion":"1.11.0",
 "tileheight":16,
 "tilesets":[
        {
         "firstgid":1,
         "source":"tileset.tsj"
        }],
 "tilewidth":16,
 "type":"map",
 "version":"1.10",
 "width":140
}

At first the height, width, tilewidth and tileheight properties stood out. They would allow me to compute how many tiles per row and per columns needed to be rendered. In the end, however, only the width and the tilewidth properties where really needed since I would render the tiles from left to right, top to bottom. I could get by only knowing how many tiles were required per row. When I ended up rendering the expected number of tiles per row, I would move down by a tile span to start rendering the next row below.

Since the tilewidth and tileheight properties had the same values due to the tiles being squares, I only needed to use one to know where to place the next tile and by how much to move down to render the next row.

However, the most important property was the one called layers. As the name implied, its value contained an array of objects containing all the needed data for each layer.

// map.json
{ 
 //... omitted for clarity
 "layers":[{...}, {...}, ...],
 //... omitted for clarity
}

A tile layer was represented with an object that had the data property. Its value was an array of numbers. At first I did not understand what it meant but then it became obvious.

// map.json
{ 
 //...
 "layers":[
   {
      "data":[ 0, 0, 0, 0, 0, 0, 0, 0, 0, 6, 3, 3, 3, 7, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 13, 12, 14, 0, 0, 0, 0, 0, 6, 3, 3, 3, 7, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 13, 12, 12, 12, 12, 12, 12, 12, 14, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
      "type":"tilelayer",
      // ... other properties omitted for clarity
   }, 
   {...}, 
   ...
  ],
 //...
}

In Tiled, each tile in the imported tileset will be assigned a number starting with 1 and then increasing from left to right, top to bottom.

The array assigned to the “data” property would contain 0 if no tile needed to be displayed therefore denoting an empty space. Otherwise, the number would determine which tile from the tileset should be rendered for a given tile in the map.

If I wanted to render a tile layer in my game, I would simply need to iterate through that array. Each iteration, I would compute the position where the tile needed to be by computing the result of the previous tile position + the tilewidth. Then, I would determine, which tile from the tileset needed to be drawn there. If the number was 0, nothing would be rendered and we would proceed to the next iteration.

While writing the rendering logic for tile layers, I experienced a problem with the way Tiled numbered tiles in the tileset compared to Kaboom.js. In Tiled, numbering starts from 1 since 0 is an empty tile. However, in Kaboom.js, numbering starts from 0.

I was able to get around this issue relatively easily by just making sure that when I needed to draw a tile, I would subtract the number in the data array by 1 to get the correct tile to display. As for when 0 occurred, as mentioned previously, I would just skip to the next element of the array after having updated the next tile position as to avoid the issue of trying to display a tile numbered 0 - 1 = -1, which wasn’t a valid index.

Finally, because I knew how many tiles were needed per row due to having access to the width and tilewidth properties, I was able to determine when to move to the next row despite the data array being one dimensional.

After having tested my code, I was able to successfully render the map onto the game’s canvas and felt overjoyed and relieved that it wasn’t as complicated as I thought it was going to be.

Finally, the last step was to render the object group layers which I would use to implement walls, obstacles and where to spawn game objects like enemies.

The object used to describe an object group layer in the “layers” array had a different shape than the one for tile layers.

// map.json
{ 
 //... omitted for clarity
 "layers":[
   {...}, 
   {
      "objects":[
        {
          "height":223.833333333333,
          "id":3,
          "name":"",
          "rotation":0,
          "type":"",
          "visible":true,
          "width":254.333333333333,
          "x":48.9166666666667,
          "y":256.166666666667
        }, 
        ...
       ],
       "type":"objectgroup",
       //... other properties omitted for clarity
      }, 
   }, 
   ...
 ],
 //... omitted for clarity
}

Rather than having a data property, we had an objects property, which instead of referencing an array of numbers, was referencing an array of objects. Each of these objects would have important properties like width, height and x, y which was all I needed to determine where to place them in my game. I would therefore, simply iterate through the objects array and create the needed game objects with the needed width and height and place them according to the x and y coordinates provided.

Since I set them up to be invisible, the player wouldn’t be able to see them, however, since Kaboom offered a debug mode, you could see their outline by pressing the f1 key.

I had finally completed the task I set out to do, and now had a more flexible way of making levels for my games. I still use this workflow to this day.

Conclusion

To conclude, game devs not using game engines, either write their own map editor or use an already existing one like Tiled to design and make their levels more efficiently.

If you’re interested in using JavaScript and the same library (now called KAPLAY) to make games, I have plenty of tutorials you can watch on my channel.

I also want to mention, that I made an exclusive step-by-step tutorial available on Patreon where I teach you how to render maps made in Tiled in your KAPLAY games in a performant and modular fashion so that you can use the same code in other KAPLAY projects.

This 40 minutes tutorial, will tackle more nuanced topics. For example, how to render polygonal colliders (useful for slopes) which differ from regular rectangular colliders. In addition, I have also bundled my paid mario-like asset pack as part of this tutorial.

You can access the tutorial here.

If you liked this post and want to see more of it, I recommend subscribing as to not miss out on future posts.

Subscribe now

In the meantime, you can read this next.

The story begins after I’d spent some time making web games in JavaScript. At the time, I was looking at the various monetization options that were available.

Unfortunately, I came to realize that the only “realistic” option was to make casual games for web game portals and monetize via ads. Something I did not find enticing. I also wanted to make deeper games which required saving user data. While you can save your player’s data in the user’s browser, this wasn’t reliable as the data could get deleted when the browser cache was cleared. I also didn’t want to pay for servers just to save user data for a single player game.

I also didn’t want to switch to other tools for 2 reasons :

The first, was that I was getting more and more proficient and comfortable with making games in JavaScript using the KAPLAY game library. Every other option I looked into would’ve taken me longer to achieve the same result than in KAPLAY. I also didn’t want to start from scratch learning a new set of tools as it would hinder my game dev progress. I wanted to just build games.

As for the second reason, I felt that making games in JavaScript wasn’t a disadvantage since they would immediately and smoothly run in the browser allowing me to reduce considerably the friction to get new players. My strategy was therefore, making the game available on the web as a demo to gauge interest while putting the full release on Steam.

This is where things got complicated. How would I convert my web game into something that can be installed and played offline on one’s PC?

After doing some research, I came across 5 technologies I could potentially use :

• Electron

• Tauri

• Wails

• Neutralino

• NW.js

Popular but Bloated

Electron is a technology that allowed developers to build desktop apps using HTML, CSS and JavaScript. Which was perfect since, my games are based on these technologies.

To achieve this, Electron would package your app with a whole Chromium browser. Your app would run in that browser.

That meant every time you installed an app made with Electron, you were also installing a Chromium browser.

Since, Chromium also consumed a lot of memory when running, apps made with it gained a reputation of being bloated. Some users started complaining but still, it did not prevent Electron to gain market share. However, this is irrelevant for games since people are more forgiving when it comes to resource usage.

Most major apps built today that are cross platform (meaning works on Mac, Windows, and Linux) are likely made with Electron. This is the case for VSCode (arguably the most popular code editor), Discord, Slack and many others.

You might be wondering why it’s this popular? This can be boiled down to three points.

1. Web developers can use a familiar set of tools to build cross-platform desktop apps rather than having to learning tools specific to each operating system.

2. You have access to most packages and libraries you can find on NPM which means you can build apps really fast.

3. The fact that it packages a specific Chromium version with your app implies that you can rest assured that your app will render and behave the same way regardless of the user’s operating system. This means less testing is required and therefore less headache on your part.

Despite all of these conveniences, when trying Electron, I found the dev experience quite annoying.

First of all, the way Electron is designed, makes you separate your app into two portions. You could view this as your “backend” and “frontend”.

The “frontend” portion, runs JavaScript that can run in the browser and interacts with the HTML.

The “backend” portion, runs JavaScript within Node.js and does not have access to the UI.

If you check my previous post : How to Start Making Games in JavaScript with No Experience, I explain in more details how JavaScript runs in two major environments.

I recommend checking it out for more details (Video version is also available here.) but to summarize, JavaScript could only be used in the browser before Node.js was invented.

With the advent of Node.js, you could now use JavaScript for backend applications that could run directly on a computer rather than within a browser.

While Electron’s approach of separating these two environments makes sense for more professional desktop app development, it does make wrapping a web game as a desktop app more tedious.

The reason is that to communicate between your “frontend” JS and your “backend” JS within an Electron app, you would need to use a IPC brigde to share only what is needed between the two.

I mostly wanted to do simple things like write my user’s save data in a file on their computer and read that same file. I found doing this in Electron more complex than what other alternatives would end up offering. I didn’t know this at the time. However, The reason I left Electron was due to the whole packaging and building executables process which I found cumbersome.

I tried using Electron Forge which was supposed to help you set up a full build pipeline. I tried using this tool because it was the one linked in the official Electron tutorial docs. What happened after trying to set it up, is that I could only build the app for the platform I was developing on. Since I was developing on a Mac and I’m making a game, having at least a Windows executable is mandatory. (Most gamers use Windows and even Linux since the advent of the Steam Deck and not Macs. I use a Mac mainly for the development experience which I find nicer than on Windows.)

Now, Electron Forge is supposed to allow you to build for the 3 major operating systems if you’re on a Mac. However, I experienced all kinds of issues for the Windows build as I needed to install WINE (which is a compatibility layer for running Windows software on Unix-like systems).

In the end, I was left with two choices, either continue to try to make it work (maybe I would have succeeded with other tools like Electron Builder) or look for alternatives.

I decided to look for alternatives and only come back if nothing else suited my needs.

Interesting but I Don’t Want to Write Rust

The second option I explored was Tauri. It was gaining popularity online and I found the way it approached desktop app development unique.

Instead of wrapping a browser with your app like Electron did, it would simply use the webview available on the user’s operating system.

At first, this sounded great, you get apps that are less bloated in size and trying it out, I found it easy to read/write files to the filesystem.

This was due to Tauri having a JavaScript API you could use for simple things like that. However, for anything more complex, you would have to write Rust.

Rust is a programming language that’s quite complicated. It’s mainly used for lower level development like operating system kernels.

I didn’t want to learn Rust as I had no use for it. Initially, I thought that just using the JS API would be enough. Unfortunately, I didn’t consider something very important.

This whole exercise I was engaged with consisted in packaging a web game to put it on Steam, therefore integrating with the Steam SDK would have been highly desirable.

With Electron, I could have achieved this using the steamwork.js package but with Tauri I couldn’t use this package since the “backend” portion of the app required me to write Rust for anything more complicated than what the JS API offered.

That was a deal breaker.

The fact that it used the default webview to render the app also meant that it wouldn’t render the same across platforms since every operating system had a webview based on a different engine. For Windows, it’s based on Edge which is now Chromium based. For Mac, it’s based on WebKit which is what is used under the hood for Safari. For Linux, it’s based on WebKitGTK which is probably similar to WebKit, but I’m not sure.

Regardless, the way a Tauri app was rendered would force me to do extensive testing on all three platforms to make sure the game was rendered the same way which would just add to my workload compared to something like Electron.

That was another deal breaker.

The last deal breaker was that, when I last used Tauri, you could only generate the executable for the current platform you were developing on. Therefore, I would have to run a Linux distro to build for Linux, run MacOS to build for Mac and run Windows to build for Windows.

It was time to look for something else.

A Similar Approach to Tauri

While I was looking up other alternatives, I came across Neutralinojs and Wails. While they didn’t end up fitting my needs in much the same way as Tauri, I thought it would be interesting to mention them.

Neutralinojs

Neutralinojs is like Tauri but without Rust. It has a JavaScript API for doing simple things like writing to a file, reading a file, etc… For anything more complex, you could hook up a separate backend in any language you want using web sockets.

Wails

Wails is also like Tauri but with Golang instead of Rust. Due to Go’s portability, it was a breeze to set up and to build executables even though the last time I tried it, I was not able to build for Linux, just Windows and MacOS. Golang is also much more approachable as a language than Rust. It doesn’t have a JS API you can use unfortunately. Integrating your game with the Steam SDK is a big question mark since Golang isn’t very used in game dev. Maybe there is a dedicated Go module for this?

The Solution

After getting a bit frustrated with all the options I tried, I was about to go back to Electron when suddenly, I had an epiphany.

Why not look up what existing JavaScript based games on Steam where using? I proceeded to go on the SteamDB website which compiled Steam related data.

Among the data gathered was a list of engines and tools used by released Steam games.

The most popular JavaScript related tool was NWJS with over 5700 games using it.

For reference:

• There are over 55000 games made with Unity.

• There are over 16900 games made with Unreal.

• There are over 2600 games made with Godot.

The info mentioned above can be found here.

I was initially caught off guard by this data because it seemed to indicate, at first glance, that JavaScript was really popular on Steam. This was unexpected because JavaScript is still viewed as a niche language amongst game developers.

After doing some research, I figured out the reason NW.js was used as much as seen on SteamDB was because RPG Maker and Construct were both popular (the former more than the latter) no-code game engines built on web technologies (JavaScript). They would use NW.js to allow their users to export their games as desktop executables.

This implicitly meant that this technology was suitable to use since it was battle tested with so many examples in the wild.

I had initially written off NW.js as a deprecated (even though still maintained) version of Electron since it was created before it and used the same principle of bundling a Chromium instance with your app. However, after having tried it. It’s really simple to use compared to Electron.

First of all, it does not make a separation between the JavaScript that runs in the browser and the one that runs in Node.js. There is no “backend” and “frontend” to worry about and no IPC bridge to set up between the two. Writing logic to save data to some file and reading that file back is really simple.

Secondly, building executables for all 3 platforms is also very easy. When you go on the official NW.js website, you download the needed pre-built binaries for the platforms you need to build for.

Then, you place it in a folder and create a new folder at the same level as the executable with the name package.nw. Finally, you put your source code in that folder.

When you click on the executable, it runs your app using the source code located in the package.nw folder. That’s it.

Now, you can run a command to merge the folder with the executable so it appears as a single .exe that you click and run. What’s left is just to rename the executable with the name of your game and maybe also change the icon with a third-party tool.

You might be wondering, doesn’t this process make it easy for someone to just pirate your game? The answer is yes but it doesn’t matter.

The Love2D game framework also works similarly. It didn’t prevent Balatro, a popular game using this framework to make millions even though the source code was easily accessible.

Conclusion

After trying all of the technologies mentioned previously, I came to the conclusion that NW.js is the easiest technology by far for wrapping a JavaScript based game for desktop.

You’re thinking of giving it a try? In that case, I have an exclusive 1-hour tutorial teaching you how to use NW.js to make a space shooter game for Mac, Windows and Linux.

In this tutorial, I’ll teach you :

• How to use Vite and NW.js together, so that you can develop for the web (therefore benefiting from hot reloading) while still being able to build an executable that will work as is. We can achieve this by using Vite’s environment variables allowing us to gate code which will run in the desktop version exclusively. This is useful when it comes to writing and reading files from/to the disk which is code that should run only in the desktop version.

• How to use NW-Builder to create a script to build executables programmatically rather than having to manually download binaries from the NW.js website.

• How to make a space shooter game using KAPLAY.

If you’re interested, check it out here.

If you enjoyed this post and want more like it, I recommend subscribing so you won’t miss out on future publications.

Subscribe now

Meanwhile, you can check these out.

It’s been a while since I started making web games in JavaScript. In this post, I’d like to share tips that would be helpful for beginners wanting to do the same.

Learn JavaScript Outside of Game Development Alongside HTML and CSS

This might sound obvious, but I really recommend learning to program before learning game dev. For JavaScript, that means learning the fundamentals of the language and how it integrates with HTML and CSS.

Considering that JavaScript is primarily used on the web to make websites and web apps, I recommend that your first few projects be web related and not game related. Game development has a lot of domain specific knowledge to grasp. A beginner would easily be overwhelmed with having to learn programming, programming in JavaScript, HTML and CSS to make the web page on which the JavaScript will run and game development all at once.

You don’t have to learn everything in JavaScript either, just the core fundamentals. You’ll learn more obscure features during practice when building projects.

Learn That There are Two JavaScripts, The one That Runs in Node.js and The one That Runs on The Web

For some time, JavaScript was relegated to a scripting language used for making web pages built using HTML and CSS, interactive. However, when the Node.js runtime was released, it allowed devs to run JavaScript outside of the browser on their machines, similarly to other languages like C#, Python, etc… This enabled JavaScript to be used for more than just websites.

There were now two major environments where JavaScript could run, in the browser and in Node.js.

When creating a server side or command line application, you would write JavasScript that would run directly on the user’s machine with Node.js. However, even for JavaScript that was intended to run on a web page, you would still use Node.js, not to run the code but to install tools useful for transforming your JavaScript before it runs on a web page.

This is due to an innovation that was brought with Node.js: The ability to download packages directly from a package manager called NPM (stands for Node Package Manager). The days where you needed to import a library by linking it using a script tag in your HTML were over.

These tools, called bundlers would bundle the libraries you installed via NPM alongside your JavaScript code and compile them into a single compact JavaScript file that you could run within a web page.

Developers would also write a more ergonomic version of JavaScript that had features not supported by browsers since they relied on the bundler to transpile whatever they wrote into JavaScript that was browser supported.

For example, React, arguably the most popular library for building web UIs, allows you to author UI components in an easy fashion by using an HTML-like syntax within your JavaScript called JSX. However, JSX is not valid in JavaScript. That’s why the bundler will transform your JavaScript code using JSX into JavaScript that doesn’t so it can run in the browser while retaining the same functionality. At the end of the day, what can be done with JSX can still be done in regular JS but in a more verbose way. That’s why we let the bundlers deal with it to make our lives easier.

All this to say, that today, most JavaScript developers, use a dev setup built around using Node.js and NPM even if the intended code is to run in the browser and not in Node.js.

For gamedev, that implies installing Node, using a build tool like Vite, installing your game frameworks/libraries via NPM, and compiling/transpiling your code to a version that can run on the web. This is often called “your build”. This build is what you deploy on your website or on platforms like itch.io.

You get a more streamlined experience from this setup since your Node.js based project keeps track of your libraries’ versions via a file called package.json (updating a library is one command away), you have access to hot reloading (meaning every time you modify your code, the change is immediately reflected which is a game changer for gamedev since this allows you to iterate quickly) and a local server is spun up automatically for you so that you can preview your project easily.

The old way of doing things is still available if you wish to avoid that complexity. For example, you can download the JavaScript file for the library, link it to you HTML using a script tag and finally install an extension like live server in VSCode to benefit from a local server and hot reloading. However, you’d still need to manually keep track of what version of the library you’re using and manually have to download new versions and replace the existing one in your project’s folder which can become tedious.

Stick to 2D, Since 3D is More Complicated

While using JavaScript for 2D games is viable, for 3D, it’s a different story. It’s very hard to compete with modern engines like Unity and Unreal which are more suited for creating 3D games and abstract away a lot of the complexity that comes with 3D.

However, there are still 3D focused libraries like Three.js but there are more suited for 3D experiences that lives on a web page rather than full fledge games. I concede that it’s still possible to make a good looking 3D game if you’re able to come up with a unique art direction. As an idea you could try replicating the HD-2D artstyle of Square Enix. Putting 2D sprites into a low poly 3D world and add post processing effects.

Pick a Framework/Library

Games made in JavaScript are rendered within the HTML canvas element of a web page. By default, you have access to the canvas API allowing you to render graphics. For those unfamiliar, it’s similar to PyGame or Love2D where you have to basically write most things from scratch.

While this is very good for learning and you’ll learn knowledge that is transferable to other lower level game dev environment, I don’t think it’s the way to go for beginners.

At least, it depends on why you’re doing game dev. If you like the technical challenges that comes with making a game, using no libraries could be more fulfilling but unfortunately time consuming. However, if you care about results, meaning having finished games, it would be wiser to use a framework or a library that offers a lot out of the box. As a beginner you’ll be more likely to finish projects which will in turn increase your motivation and increase the likelihood that you stick with game dev long term.

However, as opposed to using an engine like Unity, Godot, Unreal, using a frameworks still allows to you architect your codebase with a greater degree of freedom and prevents you from spending too much time learning how specific game engine workflows and UIs work.

For JavaScript, I recommend going with KAPLAY due to it’s simplicity and intuitive API. I have a video explaining the library in 5 minutes that you can watch next. For something more established, Phaser is the dominant player and is more performant even though it has a steeper learning curve.

Use a Map Editor like Tiled/LDTK

Manually placing objects in your game via code will get tedious quickly and make you wish you used a proper game engine. Fortunately, there is a solution. You can use a map editor like Tiled or LDTK to create your game’s levels/maps visually like you would do in game engine.

I really recommend investing the time to learn how to use one.

Stick to One Tutorial, Start to Finish

When getting started, you might be tempted to follow a project based tutorial. There’s nothing wrong with that. Just stick with it from start to finish. Don’t hop between different tutorials. Doing this will only slow down your progress.

Once you have completed following along, you can start building an original project that heavily leverages what was taught in the tutorial. It’s at that stage that you actually learn. Before that, you’re only getting exposed to various concepts without them being consolidated in your mind.

You can check some of my tutorials here.

Learn Pixel Art

Your game will sooner or later need graphics. At first, there is nothing wrong with using ready made asset packs. However, I think it’s worth the investment to learn how to make good pixel art since you’ll be able to make the sprites you need without having be dependent on an asset pack existing for your particular use case.

A nice intermediate step between using asset packs and making your own sprites from scratch is to modifiy existing asset packs. This is actually very helpful in gradually developing an understanding of what makes good pixel art.

Learning to modify asset packs well, is also very useful when you need to use multiple ones for a single project as it will allow you to make everything look consistent.

In terms of software I use is Aseprite. It’s the most popular option. However, it doesn’t really matter what software you use as long as it works for you. You can check some of the pixel art I make on my itch.io page.

Pixel art is an art form where you have the highest likelihood of making something that passes the professional quality bar in a reasonable amount of time. That’s why it’s my go-to art style.

I recommend checking my pixel art for programmers video for more tips.

Make Small Games First

This is now the standard advice parroted online but by making small games, you’re more likely to finish a project. This will in turn motivate you to continue game development and increase your skills for the next project, so on and so forth.

If you lack ideas, try remaking existing simple games like pong, duck hunt, etc… I have tutorials on my channel you can follow.

Deploying Your Games

I recommend publishing your games not only on your own website (if you have one) but on platform like itch.io where people interested in games congregate. For itch.io, you might find it hard to find players if you just upload your game. That’s why I recommend joining a game jam as you’ll be more likely to get feedback on your games that way.

Unfortunately, ways to successfully monetize web game development are rather limited. However you’re not limited to the web, you can transform your JavaScript web game into a desktop app that can be sold on Steam.

The simplest way I’ve found of achieving this was to use the NW.js technology which is similar to the more popular Electron but much simpler to use.

I have an exclusive step by step tutorial on Patreon teaching you how to make a downloadable desktop space shooter game with KAPLAY and NW.js for Mac, Windows and Linux.

Check it out here!

Conclusion

Hope these tips where useful in your JavaScript game development journey. If you’re interested in more content like this, consider subscribing to not miss out when I post something new.

Subscribe now

Hi, in this post, I’ll try to explain what is KAPLAY and what are its major concepts in 5 minutes. Let’s get started!

First of all, KAPLAY is an open source library for making games in JavaScript and TypeScript.

It has built-in support for rendering, asset loading, input handling, animations, audio playback, collision detection and physics.

Contrary to Phaser, KAPLAY isn’t OOP (Object-Oriented-Programming) based, instead it offers an entity component system (ECS) where you build game objects using components. Each component enables the game object to have access to certain features, properties and methods.

In KAPLAY, a game object is created by passing an array of components to the add function. For example, using the sprite component will allow the game object to be rendered as a sprite. The area component will create a hitbox useful for collision detection. It can be seen using KAPLAY’s debug mode by pressing the f1 key or the fn+f1 keys on a Mac. Finally, the pos component is used to set its position on the canvas.

KAPLAY offers a bunch of ready-made components, increasing development speed. However, you can create your own components if you wish to.

Additionally, passing a JavaScript object to the array of components, allows us to define custom properties and methods which removes the need to create classes like in the OOP (Object-Oriented Programming) paradigm.

As for animations, KAPLAY offers an intuitive animation API. To load a spritesheet use the loadSprite function, pass to it a name you want to use to refer to the spritesheet, the path where the image is located and finally an object telling KAPLAY how to slice it into single frames. This object, should have the sliceX property determining the number of frames per row, the sliceY property determining the number of frames per column and an anims property containing an object for configuring animation data.

To define an animation, you can pass a key object pair to the anims object. The key determines the name of the animation. The value can be an object with the from property containing the number of the frame where the animation starts, the to property for determining the last frame of the animation and optionally, a loop property containing a boolean where you can set the animation to loop indefinitely and a speed property for setting the speed at which the animation will play.

Finally, to play an animation, you can either use the play method available on any game object that uses the sprite component or pass the animation you want to play as a second param to the sprite component where the game object is defined.

Another important concept of KAPLAY are scenes. To create a scene you need to call the scene function and pass a string defining the scene’s name and a function that will run the scene’s logic. You can use the go function to navigate from one scene to another and even pass data to other scenes.

KAPLAY also offers functions for handling user input with support for controller, mouse and keyboard.

You can define virtual buttons in the KAPLAY context where your game is initially configured. Once done, you can use the onButtonPress, onButtonDown, onButtonReleased methods for handling input. For example, the onButtonPress function will be provided a function which will run when any button is pressed. The name of the button being pressed will be passed to that function which you can use to determine whenever to run some logic.

In addition to components and JavaScript objects, you can pass a string to the array of components to give an identifier to a game object. These are called tags and they’re very useful.

A prime example of their use, is for collision detection. Using KAPLAY’s onCollide function you can use tags to handle collisions between two games objects or a game object and a group of game objects or two groups.

Tags are also useful for querying game objects. Using KAPLAY’s get function you can provide it with a tag and it will return all game objects having that tag.

KAPLAY also has a physics system included which is very easy to use. You can set the gravity per scene by using the setGravity function. To make a game object susceptible to gravity, use the body component. As for a game object acting as a platform, you can within the body component, pass an object with an isStatic property set to true to prevent it from falling off or moving. Additionally, using this component enables the game object to use KAPLAY’s built in jump method. Therefore, you don’t have to implement a jump mechanic yourself.

Another very useful KAPLAY concept is the ability of creating child game objects using the add method available on the parent. You can use the pos component to offset the child’s position vis-a-vis the parent. This makes implementing certain mechanics easier.

Sometimes, you need to run logic every frame. For this purpose, you can create an update loop by using the onUpdate function. Alternatively, you can attach an update loop to a specific game object so that if it ends up destroyed, the update loop is cancelled.

Finally, KAPLAY can be installed like any JavaScript library using a script tag or with NPM but you can also use its web based editor called KAPLAYGROUND which is free.

There are many KAPLAY concepts I haven’t covered here but I hope it gave you a quick overview of the library and helped you determine if you want to invest your time learning it.

If you want to dive deeper, check my project based tutorials using KAPLAY on YouTube. You can also check the API reference and examples in the KAPLAY docs.

Additionally, I offer exclusive KAPLAY tutorials on Patreon. Link is here.

Subscribe now

I have made available a PDF version of my Sonic TypeScript KAPLAY tutorial.

With the PDF, you get :

• Nice formatting, making the text very easy to read.

• Everything in a single 34 pages document.

• Syntax highlighting for code.

• Easy to navigate table of contents.

Here is a preview of the PDF.

Buy it for 5$

KAPLAY is a recent JavaScript/TypeScript library for making games. It originated from the now defunct Kaboom.js library. (In fact, it’s a direct fork of Kaboom)

Since the library is new, it is often overshadowed by more popular libraries/frameworks like Phaser, Pixi.js, Three.js, etc…

While writing about the merits of KAPLAY might convince some to give it a try, I think listing interesting games made with it, might be more effective.

Here is a list of games made with KAPLAY in no particular order.

Pharaoh's Tomb HD – A Remake Made in KAPLAY

This is a remake of the old MS-DOS game called Pharaoh’s Tomb.

Play Game

Clickery Hexagon

Clickery Hexagone is a very polished clicker style game. The game is relatively popular on Newgrounds (a Web game portal).

Play Game

Golf Course: Ocean Wave Edition

A short mini-golf game set in the ocean. This game could easily be on Steam considering how much attention to detail there is.

Play Game

Duck Hunter

A clone of the classic game Duck Hunt. I made this one.

Play Game

Soil Defender

A Plant VS Zombie-like game developed as part of the Earth Journalism Network. Not common to see games used for journalism.

Play Game

Conclusion

I hope this list gave you an idea of what you can achieve with KAPLAY. If you’re aware of other games you think should be showcased here, don’t hesitate leaving a comment below.

In the previous part of the tutorial, we finished implementing Sonic’s movement and jumping logic. We also implemented platforms and background infinite scrolling.

In this part, we will finish what remains to be implemented.

Table of Contents

• Implementing Rings for Sonic to Collect

• Implementing a Scoring System

• Adding Enemies

  • Implementing Collision Logic With Enemies

• Finishing The Scoring UI

• Implementing The Game Over Scene

• Deployment

• Conclusion

Implementing Rings for Sonic to Collect

In the entities.ts file, add the following code :

// ... previous code omitted for clarity

export function makeRing(position: Vec2) {
  return k.add([
    k.sprite("ring", { anim: "spin" }),
    k.area(),
    k.scale(3),
    k.anchor("center"),
    k.pos(position),
    k.offscreen(),
    "ring",
  ]);
}

Import the needed assets in main.ts.

// ... last loadSprite call
k.loadSprite("ring", "graphics/ring.png", {
  sliceX: 16,
  sliceY: 1,
  anims: {
    spin: { from: 0, to: 15, loop: true, speed: 30 },
  },
});
// ... loadSound call

The makeRing function creates a ring game object. The offscreen component adds an onExitScreen method to that game object (used later in the tutorial) to destroy it once it leaves the screen.

“ring” is a tag used to identify the game object in collision logic which we will later cover. Multiple game objects can have the same tag.

In main.ts, add the following logic in the game scene to spawn rings.

// ... previous import statement
import { makeSonic, makeRing } from "./entities";

k.scene("game", () => {

  // ... code omitted for clarity

  const spawnRing = () => {
    const ring = makeRing(k.vec2(1280, 610));
    ring.onUpdate(() => {
      ring.move(-gameSpeed, 0);
    });
    ring.onExitScreen(() => {
      k.destroy(ring);
    });

    const waitTime = k.rand(0.5, 3);

    k.wait(waitTime, spawnRing);
  };

  spawnRing();

  // k.onUpdate(() => ...) code omitted for clarity
});

We create a recursive function called spawnRing. When called, it first creates a ring by calling makeRing. In KAPLAY, you can set an onUpdate loop specific to a game object that will be destroyed if the game object is destroyed. In that update loop, we make the ring move to the left at the same rate as the game’s speed. This will give the illusion that Sonic is approaching the ring while in reality, it’s the contrary.

We use the onExitScreen method to destroy the ring when it exits the screen to the left.

Using KAPLAY’s rand function we’re able to get a random number between 0.5 and 3 representing the time to wait before spawning another ring.

KAPLAY’s wait function is used to only call the spawnRing function once the wait time is elapsed.

Implementing a Scoring System

Now that the rings are spawned we need to write the logic for Sonic to collect them. Which implies needing to keep track of the score.

In main.ts, under our game scene, add the following code :

// ... asset loading logic
k.loadFont("mania", "fonts/mania.ttf");

k.scene("game", () => {
  // ... gameSpeed loop  

  let score = 0;
  let scoreMultiplier = 0;
  const scoreText = k.add([
    k.text("SCORE : 0", { font: "mania", size: 48 }),
    k.pos(20, 20),
    k.z(2),
  ]);
  
  // ... rest of the code omitted for clarity
});

In addition to creating variables related to the score, we created a game object acting as our score UI. Using the text component, we’re able to display text on the screen. The second param of that component is used to set the font and sizing needed.

Finally, we use the z component to make sure the score UI is always displayed on top of other game objects by setting it’s z layer to 2.

You should have the following result.

Now, let’s update the score every time Sonic collides with a ring. Add the following code in our game scene :

import { GameObj } from "kaplay";

// asset loading logic
k.loadSound("ring", "sounds/Ring.wav");

k.scene("game", () => {

  // after makeRing();

  sonic.onCollide("ring", (ring: GameObj) => {
    k.play("ring", { volume: 0.5 });
    k.destroy(ring);
    score++;
    scoreText.text = `SCORE : ${score}`;
  });

  // before k.onUpdate(() => ...)

});

We used Sonic’s built-in onCollide method which takes as the first param the tag of a game object you want to check collisions with. The second param is a function that will run in case a collision does occur. Here, we play the “ring” sound and then destroy the ring game object Sonic collided with. Finally, we increment the score and change the score UI’s text to reflect the new score.

If you run the game now, you should see the score updating every time Sonic collides with a ring.

Adding Enemies

The code needed for adding enemies to our game is going to be very similar to the one for adding rings. The only difference is that, contrary to rings, if Sonic touches an enemy, it’s game over. However, if Sonic jumps on that enemy, the enemy gets destroyed.

In entities.ts, add the following code :

// ... previous code omitted for clarity

export function makeMotobug(position: Vec2) {
  return k.add([
    k.sprite("motobug", { anim: "run" }),
    k.area({ shape: new k.Rect(k.vec2(-5, 0), 32, 32) }),
    k.scale(3),
    k.anchor("center"),
    k.pos(position),
    k.offscreen(),
    "enemy",
  ]);
}

Here, we defined a function for creating our enemy, the “Motobug”. We used components that should now be familiar to you. However, you might have noticed that we pass an object to the area component. This is something you can do to define a custom hitbox shape. Here, we’re setting the shape of the hitbox to be a rectangle using KAPLAY’s Rect constructor. It allows you to set the hitbox’s origin relative to the game object. If you pass k.vec2(0,0), the origin will be the same as the game object’s. The second and third param of the constructor are used to set the width and the height of the hitbox.

Once we will add enemies to the game, you’ll be able to use the debug mode to view how our hitbox configuration for Motobug is rendered.

Add the following code to main.ts :

// ... import statements omitted for clarity
import { makeSonic, makeRing, makeMotobug } from "./entities";

// ... previous asset loading statements omitted for clarity
k.loadSprite("motobug", "graphics/motobug.png", {
  sliceX: 5,
  sliceY: 1,
  anims: {
    run: { from: 0, to: 4, loop: true, speed: 8 },
  },
});

k.scene("game", () => {
  // ... previous code omitted for clarity

  const spawnMotoBug = () => {
    const motobug = makeMotobug(k.vec2(1280, 595));
    motobug.onUpdate(() => {
      if (gameSpeed < 3000) {
        motobug.move(-(gameSpeed + 300), 0);
        return;
      }
      motobug.move(-gameSpeed, 0);
    });

    motobug.onExitScreen(() => {
      k.destroy(motobug);
    });

    const waitTime = k.rand(0.5, 2.5);

    k.wait(waitTime, spawnMotoBug);
  };

  spawnMotoBug();

  // k.onUpdate(() => ...);
});

The logic for spawning “Motobugs” is mostly the same compared to the one for “rings”. However, the “Motobug”s update loop is slightly different.

motobug.onUpdate(() => {
  if (gameSpeed < 3000) {
    motobug.move(-(gameSpeed + 300), 0);
    return;
  }
  motobug.move(-gameSpeed, 0);
});

When the game’s speed is inferior to 3000 we make the “Motobug” move faster than the scrolling of the platforms so that it appears as moving on the platforms towards Sonic. Otherwise, it would look like Sonic is the one moving towards stationary “Motobugs”.

However, when the game’s speed gets really fast, it isn’t possible to really tell the difference. In that case, we simply make the “Motobug” move at the same rate as the scrolling platforms.

At this point, you should see enemies spawn in your game.

Implementing Collision Logic With Enemies

At the moment, if Sonic collides with an enemy, nothing happens. Likewise, if he jumps on one.

Let’s add the following code in main.ts :

// ... previous asset loading logic omitted for clarity
k.loadSound("hyper-ring", "sounds/HyperRing.wav");
k.loadSound("destroy", "sounds/Destroy.wav");
k.loadSound("hurt", "sounds/Hurt.wav");

k.scene("game", () => {
   // ... previous code omitted for clarity

   sonic.onCollide("enemy", (enemy) => {
    if (!sonic.isGrounded()) {
      k.play("destroy", { volume: 0.5 });
      k.play("hyper-ring", { volume: 0.5 });
      k.destroy(enemy);
      sonic.play("jump");
      sonic.jump();
      scoreMultiplier += 1;
      score += 10 * scoreMultiplier;
      scoreText.text = `SCORE : ${score}`;
      return;
    }

    k.play("hurt", { volume: 0.5 });
    k.setData("current-score", score);
    k.go("game-over");
  });

  // reset multiplier when Sonic hits the ground
  sonic.onGround(() => {
    scoreMultiplier = 0;
  });
  // k.onUpdate(() => ...)

});

If you run the game now, you should be able to jump on enemies and if Sonic hits an enemy while grounded, you will be transitioned over to an empty game over screen.

You’ll notice that we added logic to multiply the player’s score if they jump on multiple enemies before hitting the ground.

We’re also registering the current player score in local storage so we can display it later in the game over scene.

Finishing The Scoring UI

Since our game is very fast paced, it’s hard for players to keep track of how many rings they’re collecting. They would have to look up to the top left of the screen while risking not seeing an enemy in time to avoid it/jump on it.

To mitigate this and to give the player a better sense of what they’re doing, I opted to display the number of rings collected after every collision with a ring or a jump on an enemy. This will also make combos easier to understand.

Add the following code in main.ts to implement this feature :

k.scene("game", () => {
  // ... previous code omitted for clarity
  // sonic.setEvents();

  const ringCollectUI = sonic.add([
    k.text("", { font: "mania", size: 18 }),
    k.color(255, 255, 0),
    k.anchor("center"),
    k.pos(30, -10),
  ]);

  // ...
  sonic.onCollide("ring", (ring: GameObj) => {
    //... previous code omitted for clarity
    ringCollectUI.text = "+1";
    k.wait(1, () => {
     ringCollectUI.text = "";
    });
  });
  
  // ...
  sonic.onCollide("enemy", (enemy) => {
    if (!sonic.isGrounded()) {
      // ... previous code omitted for clarity
      if (scoreMultiplier === 1)
        ringCollectUI.text = `+${10 * scoreMultiplier}`;
      if (scoreMultiplier > 1) ringCollectUI.text = `x${scoreMultiplier}`;
      k.wait(1, () => {
        ringCollectUI.text = "";
      });
      return;
    }
    // ...
  });
});

Now, if you run the game, you should see a +1 appear every time Sonic collides with a ring and a +10, x2, x3, etc… when he jumps on one or many “Motobugs”.

An important concept present in the code above, is that game objects can have child game objects assigned to them in KAPLAY. This is what we do here :

const ringCollectUI = sonic.add([
  k.text("", { font: "mania", size: 18 }),
  k.color(255, 255, 0),
  k.anchor("center"),
  k.pos(30, -10),
]);

Instead of calling the add function to create a game object, we can call the add method to create a child game object of an existing game object. Here, we create the ringCollectUI as a child of Sonic so that its position is relative to him.

Implementing The Game Over Scene

Finally, for our game over screen, let’s display the player current VS best score and allow them to try the game again if they wish to.

In the game over scene code in main.ts, add the following :

k.scene("game-over", () => {
  let bestScore = k.getData("best-score") || 0;
  const currentScore = k.getData("current-score") || 0;

  if (currentScore && bestScore < currentScore) {
    k.setData("best-score", currentScore);
    bestScore = currentScore;
  }

  k.add([
    k.text("GAME OVER", { font: "mania", size: 64 }),
    k.anchor("center"),
    k.pos(k.center().x, k.center().y - 300),
  ]);
  k.add([
    k.text(`BEST SCORE : ${bestScore}`, {
      font: "mania",
      size: 32,
    }),
    k.anchor("center"),
    k.pos(k.center().x - 400, k.center().y - 200),
  ]);
  k.add([
    k.text(`CURRENT SCORE : ${currentScore}`, {
      font: "mania",
      size: 32,
    }),
    k.anchor("center"),
    k.pos(k.center().x + 400, k.center().y - 200),
  ]);

  k.wait(1, () => {
    k.add([
      k.text("Press Space/Click/Touch to Play Again", {
        font: "mania",
        size: 32,
      }),
      k.anchor("center"),
      k.pos(k.center().x, k.center().y + 200),
    ]);
    k.onButtonPress("jump", () => k.go("game"));
  });
});

While it should be relatively easy to figure out what the code above does, I’d like to explain what we do here :

let bestScore: number = k.getData("best-score") || 0;
const currentScore: number = k.getData("current-score") || 0;

if (bestScore < currentScore) {
  k.setData("best-score", currentScore);
  bestScore = currentScore;
}

Using KAPLAY’s getData function we’re able to get the data we previously set in local storage. However, when the player plays the game for the first time, they will not have a best score. That’s why we set bestScore to be 0 if k.getData(“best-score”) returns null which is possible. We do the same with currentScore.

Now, if you run the project, you should have the following game over screen appear after getting hit by an enemy. After, 1 sec you should be able to press the “Jump” button (in our case click or press the space key) to play the game again.

Deployment

Assuming you want to be able to publish the game in web portals like itch.io, you can make a build by creating a vite.config.ts file at the root of your project’s folder and specifying the base as ./.

import { defineConfig } from "vite";

export default defineConfig({
  base: "./",
});

Now, run the command npm run build and you should see a dist folder appear in your project files. Make sure your game still works by testing the build using npm run preview. Finally, once ready to publish, zip your dist folder and upload it to itch.io or to other web game platforms of your liking.

Conclusion

Hope you enjoyed learning how to make games in TypeScript with KAPLAY. If you’re interested in seeing more web developement and game development tutorials from me. I recommend subscribing to not miss out on future releases.

Subscribe now

If you’re up for it, you can check out my beginner React.js tutorial.

In this tutorial, I’ll teach you how to make a simple Sonic themed infinite runner game in TypeScript using the KAPLAY game library.

You can play the game here. The final source code for it is available here.

In this game, you need to collect as many rings as possible. Jumping on enemies grants you a bonus of 10 rings. Continually jumping on enemies without touching the ground gives you a multiplier on each enemy. The first enemy grants you +10, the second +(10 x 2), the third +(10 x 3), etc…

The challenge comes from the game getting progressively faster, making it harder to avoid getting hit by enemies. I really recommend playing the game to have a better idea of what we’re going to build.

Prerequisites

I expect that you have basic familiarity with TypeScript or are, at the very least, competent in JavaScript. We’re going to write the game in TypeScript, but it’s going to be very easy TypeScript code. Since we will rarely, if ever, need to write custom types. You should be familiar with Node.js and NPM and have them installed on your machine before following this tutorial. I do not expect you to know KAPLAY.

Table of Contents

• What is KAPLAY?

• Project Setup

• Initializing The Canvas

• Creating Scenes

• Loading Assets

• Implementing an Infinite Scrolling Background

  • What are Game Objects and Components in KAPLAY?

  • Implementing Movement With an onUpdate Loop

• Implementing an Infinite Scrolling Platform

• Implementing The Sonic Game Object

  • How Animations Work in KAPLAY

  • How Hitboxes Are Created in KAPLAY

  • How to Add Methods to a Game Object

• Adding Sonic to Our Game

  • Creating a Static Body as The Floor

  • Placing Sonic in The Game Scene

• Conclusion

What is KAPLAY?

KAPLAY is an open source library for making games in JavaScript and TypeScript.

Compared to the more popular Phaser JavaScript game framework, its API is a lot simpler making it easier for beginners to pick up. It also offers a lot of premade functionality out of the box. You spend therefore, less time reinventing the wheel.

For those familiar with the Godot game engine, you might be accustomed to the concept of nodes which acts as building blocks containing out of the box functionality. KAPLAY has a somewhat similar concept to nodes called components.

You can check the official KAPLAY website for more info here.

Project Setup

Create a folder called sonic-runner. cd within using your terminal of choice and run :

npm create vite@latest .

This command will scaffold a TypeScript project within the existing folder using the popular build tool Vite.

Once the command runs, you’ll be presented with the following :

> npx
> create-vite .

│
◆  Select a framework:
│  ● Vanilla
│  ○ Vue
│  ○ React
│  ○ Preact
│  ○ Lit
│  ○ Svelte
│  ○ Solid
│  ○ Qwik
│  ○ Angular
│  ○ Others
└

Pick “Vanilla”. You’ll be presented with another menu to chose between JavaScript and TypeScript. Select TypeScript.

> npx
> create-vite .

│
◇  Select a framework:
│  Vanilla
│
◆  Select a variant:
│  ● TypeScript
│  ○ JavaScript
└

Now let’s install the KAPLAY library. We will install the specific version called v3001.0.16. Run the following :

npm install kaplay@3001.0.16

This version is the latest stable version available at the time this tutorial was written. As long as you stick with this specific version, you shouldn’t have issues following this tutorial years into the future.

Once installed, take a look at your package.json file in your project’s folder. You’ll notice that KAPLAY was added to your dependencies.

{
  "name": "sonic-runner-ts",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  },
  "devDependencies": {
    "typescript": "~5.7.2",
    "vite": "^6.3.1"
  },
  "dependencies": {
    "kaplay": "^3001.0.16"
  }
}

When we used the npm create command, Vite created a bunch of files. Make sure that you have the following project structure. Remove everything within the src folder as we’re going to write everything from scratch.

- node_modules // should be git ignored in .gitignore
- public
- src
- .gitignore
- index.html
- package-lock.json
- package.json
- tsconfig.json

Once everything is removed in src, create two files within. One named kaplayCtx.ts and the other main.ts. You should have the following project structure.

- node_modules // should be git ignored in .gitignore
- public
- src
   |- kaplayCtx.ts
   |- main.ts
- .gitignore
- index.html
- package-lock.json
- package.json
- tsconfig.json

Finally, the last step of our setup is to bring in our game assets. Copy the contents of the public folder provided in the game’s final source code available on GitHub. The repo can be accessed by clicking here.

After having done so, you should have the following files in your public folder.

- public
   |- fonts
        |- mania.ttf
   |- graphics
        |- chemical-bg.png
        |- motobug.png
        |- platforms.png
        |- ring.png
        |- sonic.png
   |- sounds
        |- Destroy.wav
        |- Hurt.wav
        |- HyperRing.wav
        |- Jump.wav
        |- Ring.wav
   |- vite.svg

Initializing The Canvas

Now that our setup is complete, we can initialize an HTML canvas in which the game will be rendered. This will be done through KAPLAY by initializing our context which will also allow us to use KAPLAY functions.

In kaplayCtx.ts, write the following code :

import kaplay from "kaplay";

const k = kaplay({
  width: 1280,
  height: 720,
  letterbox: true,
  global: false,
  buttons: {
    jump: {
      keyboard: ["space"],
      mouse: "left",
    },
  },
  touchToMouse: true,
  debug: true, // set it to false when deploying the game
  pixelDensity: window.devicePixelRatio,
});

export default k;

Our context is created by calling the kaplay function and passing an object containing various options we want to configure for our game. We first set the width and the height of the canvas.

We set the letterbox property to true, allowing our game canvas to scale regardless of the screen size while still retaining its aspect ratio.

We set the global property to false so that KAPLAY functions can only be used via the constant k. This will lead to more legible code since you’ll be able to easily detect if a KAPLAY function is in use by noticing k.nameOfTheFunction.

We pass an object to the buttons property to define the jump action of our game. Since, we want to make the game playable on both desktop and mobile, we set the jump custom action to be mapped to the space key or the left mouse click. jump is an arbitrary name and you could have decided on something different. You can also add an arbitrary amount of actions depending on your game’s needs by adding a new property. For example :

buttons: {
    jump: {
      keyboard: ["space"],
      mouse: "left",
    },
    moveLeft: {
      keyboard: ["left"],
    },
   /// etc...
},

The touchToMouse property is used to convert touch input to mouse clicks so that the game is playable on mobile.

The debug property is used to toggle on/off KAPLAY’s debug mode. This mode can be accessed on the webpage the game is running on by pressing the f1 key or the fn+f1 keys on a Mac. It will display an fps counter along with the game objects’ hitboxes which makes debugging easier. We will use it later in this tutorial. Here, we’re setting debug to true so that the debug mode is accessible.

One thing to note is that by default, debug mode is available so you don’t need use this property initially. The reason I included it here, is that when you ultimately deploy your game, you might not want your players to access this mode. Therefore, setting this property to false before deployment is a good idea.

Finally, to make the game display sharply regardless of the screen we set the pixelDensity property to correspond to the pixel ratio of the current screen. You’ll notice that not using this property will make the game render slightly blurry on certain screens.

We then export the constant k containing a reference to the context, so that we can use it elsewhere in our code.

Creating Scenes

Our game will have two scenes. The first, is where the game takes place while the second, is a game over screen displaying the player’s score.

In KAPLAY, you can create mulitple scenes using the scene function. In our main.ts file let’s import the KAPLAY context and create our scenes.

import k from "./kaplayCtx";

k.scene("game", () => {
  // TODO
});

k.scene("game-over", () => {
  // TODO
});

k.go("game");

Here we created two scenes. The scene function takes, as the first param, the name you want to use to refer to that scene. The second param is a function that will run when the game enters that scene.

Finally, we also need to use the go function to tell KAPLAY which scene to go to when the game starts. This function is also used to navigate to other scenes when called within a specific scene.

We will write the logic for each scene later, now let’s run our project to see if we have correctly initialized our canvas.

In your terminal, run the command :

npm run dev

VITE v6.3.4  ready in 229 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

When you open the localhost address in your browser, if everything went well, you should see a checkered canvas like shown below.

If you try to resize your window, you’ll also notice that the canvas seems to always preserve its aspect ratio. This is exactly what we want so that the game is playable on any device.

Loading Assets

In main.ts let’s load the assets we need for the background and the platforms. This will be a good introduction to how assets are loaded in KAPLAY. Add the following code :

import k from "./kaplayCtx";

k.loadSprite("chemical-bg", "graphics/chemical-bg.png");
k.loadSprite("platforms", "graphics/platforms.png");

//... rest of the code omitted for clarity

Here we use KAPLAY’s loadSprite function. It takes, as the first param, a string which corresponds to the name you want to use to refer to that specific sprite/image. For the second param, the function expects the path to the asset.

Note that we don’t need to add the public folder to the path since Vite makes sure to make whatever is in that folder accessible as if it was placed at the root of the project.

Implementing an Infinite Scrolling Background

In our game, the city background must scroll indefinitely. Let’s implement this in our game scene. Add the following code in main.ts :

k.scene("game", () => {
  const bgPieceWidth = 2880;
  const bgPieces = [
    k.add([
      k.sprite("chemical-bg"),
      k.pos(0, 0), 
      k.opacity(0.8), 
      k.scale(1.5)
    ]),
    k.add([
      k.sprite("chemical-bg"),
      k.pos(bgPieceWidth, 0),
      k.opacity(0.8),
      k.scale(1.5),
    ]),
  ];

  k.onUpdate(() => {
    if (bgPieces[1].pos.x < 0) {
      bgPieces[0].moveTo(bgPieces[1].pos.x + bgPieceWidth * 2, 0);
      const frontBgPiece = bgPieces.shift();
      // so typescript shuts up
      if (frontBgPiece) bgPieces.push(frontBgPiece);
    }

    bgPieces[0].move(-100, 0);
    bgPieces[1].moveTo(bgPieces[0].pos.x + bgPieceWidth * 2, 0);
  });
});

Let’s break it down.

const bgPieceWidth = 2880;
const bgPieces = [
  k.add([
    k.sprite("chemical-bg"),
    k.pos(0, 0), 
    k.opacity(0.8), 
    k.scale(1.5)
  ]),
  k.add([
    k.sprite("chemical-bg"),
    k.pos(bgPieceWidth, 0),
    k.opacity(0.8),
    k.scale(1.5),
  ]),
];

To achieve an infinite scrolling background, we need need to display the same background image twice. The trick is to reposition the first image behind the second one once it leaves the screen. The second image becomes the first and the first becomes the second. The same logic is repeated indefinitely.

I previously wrote a post specific to infinite backgrounds with easy to understand visuals. You can check it out below.

In the code above, we first set a constant holding the width of the background image when scaled by 1.5, which corresponds to 1920 x 1.5 = 2880 since the original image has a width of 1920. This is needed so that we can position the second copy right after the first one without leaving any gaps. We will display the background at 1.5 its original scale so that it looks nice within our game.

We then set an array containing the two copies. Each copy is created using KAPLAY’s add function which creates a game object, one of KAPLAY’s major concepts.

What are Game Objects and Components in KAPLAY?

A game object represents an entity rendered on the canvas and is composed of components. These components determine various methods and features that it has access to. KAPLAY provides these components out of the box but you can also create custom ones if you wish to (We won’t in this tutorial).

k.add([
  k.sprite("chemical-bg"),
  k.pos(0, 0), 
  k.opacity(0.8), 
  k.scale(1.5)
]),

The add function used to create game objects, takes an array of KAPLAY components. Let’s break down the 4 we use here :

• sprite comp : Renders a game object as a visible sprite/image.

• pos comp : Sets the position of a game object on the canvas using (x, y) coordinates. In KAPLAY and in many other game libraries, the x coordinate increases the further you go right and the y coordinate increases the further you go down. The origin (X = 0, Y = 0) is set at the top-left corner of the canvas.

• opacity comp : Sets the opacity of a game object using a value between 0 and 1. The closer the value is to 0 the more it becomes transparent.

• scale comp : Sets the scale of a game object. Is often used alongside the sprite comp to change the sprite/image’s size on the canvas.

k.add([
  k.sprite("chemical-bg"),
  k.pos(bgPieceWidth, 0), 
  k.opacity(0.8), 
  k.scale(1.5)
]),

As you can see, the second copy uses the same components. However, we set the position differently so that it is rendered right behind the first one without leaving any gaps.

Implementing Movement With an onUpdate Loop

While creating game objects using the add function will render them on the canvas, no movement will occur without an update loop.

The update loop runs every frame and is used to update our game’s logic. If your game runs at 60fps, the loop will run 60 times per second. In KAPLAY, we use the onUpdate function to set our update loop.

k.onUpdate(() => {
  if (bgPieces[1].pos.x < 0) {
    bgPieces[0].moveTo(bgPieces[1].pos.x + bgPieceWidth, 0);
    const frontBgPiece = bgPieces.shift();
    // so typescript shuts up
    if (frontBgPiece) bgPieces.push(frontBgPiece);
  }

  bgPieces[0].move(-100, 0);
  bgPieces[1].moveTo(bgPieces[0].pos.x + bgPieceWidth, 0);
});

We first check if the background image second copy’s x position is < 0. In that case, we can assume that the first copy is offscreen and therefore, we can safely attempt to move it behind the second copy. This is achieved by setting its position using the moveTo KAPLAY method made available due to using the pos comp when the game object was defined.

Using the shift array method we delete the first element from the array and return it. Finally, we push it back to the array so that the first copy is now placed as the second element of the array making it become the second copy. Another if statement is used to make sure the result of shift() is not undefined before pushing it to the array again. Otherwise, TypeScript will complain and rightly so.

Regardless of all of the above, on each iteration of the loop, we move both copies to the left by using the move KAPLAY method on the first copy and the moveTo method on the second copy to follow the first copy. Both these methods exists because we used the pos component when creating each respective game object.

The move method takes two params. The first is for setting the velocity of the game object on the x axis while the second sets the velocity on the y axis. By setting the x velocity to -100 and the y velocity to 0, we’re moving only to the left at a velocity of 100 pixels/second.

If you’re accustomed to other game engines/frameworks, you might have noticed the absence of deltaTime (corresponds to the time elapsed since the last frame in our game loop) being used to make our movement frame rate independent. This is because the move method takes care of it under the hood.

Now, looking at your browser tab (Assuming that you have localhost running) you should see the city background scrolling indefinitely.

To make the background less distracting during gameplay, I opted to set its opacity to 0.8 instead of 1. Now, if you go back to your kaplayCtx.ts, we can set the background of the whole webpage to be black. This will result in the city background becoming darker and therefore less distracting during gameplay.

const k = kaplay({
  width: 1280,
  height: 720,
  letterbox: true,
  global: false,
  buttons: {
    jump: {
      keyboard: ["space"],
      mouse: "left",
    },
  },
  touchToMouse: true,
  debug: true,
  pixelDensity: window.devicePixelRatio,
  background: [0, 0, 0], // <--- new line
});

We provide to the background property an array of three elements each representing one of the RGB color channels. Each element’s value can vary between 0 to 255. This is what’s used to represent color. If you check your browser tab, you should notice that the city background is now darker.

Implementing an Infinite Scrolling Platform

Our game is based on one big illusion. Sonic isn’t actually running. The platform on which Sonic stands isn’t actually moving. The only things moving are the background and the platform’s image which are made to scroll indefinitely.

If we were to remove all of the game’s graphics, we would be left with a game object representing the player that can jump up and land on a static floor.

Our goal at the moment, is to implement infinite scrolling platforms the same way we did for the city background. The only difference is that the scrolling speed will increase the further the game progresses.

In main.ts add the following code :

// previous code omitted for clarity
k.scene("game", () => {
  let gameSpeed = 100;
  k.loop(1, () => {
    gameSpeed += 50;
  });

  // code for the city background omitted for clarity

  const platformWidth = 2560;
  const platforms = [
    k.add([k.sprite("platforms"), k.pos(0, 450), k.scale(2)]),
    k.add([k.sprite("platforms"), k.pos(2560, 450), k.scale(2)]),
  ];

  k.onUpdate(() => {
    // city background update logic omitted for clarity

    if (platforms[1].pos.x < 0) {
      platforms[0].moveTo(
        platforms[1].pos.x + platformWidth,
        platforms[1].pos.y
      );
      const frontPlatform = platforms.shift();
      if (frontPlatform) platforms.push(frontPlatform);
    }

    platforms[0].move(-gameSpeed, 0);
    platforms[1].moveTo(platforms[0].pos.x + platformWidth, platforms[0].pos.y);
  });
});

We first set a gameSpeed variable that is incremented every second using KAPLAY’s loop function. This is similar to JavaScript/TypeScript’s setInterval function. The first param is for setting the time between each call and the second param is the function that will be called.

Similarly to the city background, we create two copies of the platforms’ image so that we can achieve infinite scrolling. platformWidth corresponds to the final width of the platforms’ image after scaling it twice. This is because we need to make the platforms bigger in our game to make it look good. We use this constant to know where to place the second copy behind the first one without leaving any gaps.

The update logic is also similar, the only difference this time is that the move function takes the gameSpeed variable as the x velocity allowing for it to increase the platforms speed through time.

If you run the project, you should notice the platforms scrolling slowly and then gradually increase in speed as time passes.

Implementing The Sonic Game Object

Now that we have our game scene mostly done, we’re ready to work on adding Sonic to our game.

Sonic, the rings he must collect and the enemies are all entities. Let’s create a file named entities.ts in the src folder. Then, let’s create a game object that will hold Sonic’s logic.

src
|- kaplayCtx.ts
|- main.ts
|- entities.ts

In entities.ts add the following code.

import k from "./kaplayCtx";
import { Vec2, GameObj } from "kaplay";

export function makeSonic(position: Vec2) {
  return k.add([
    k.sprite("sonic", { anim: "run" }),
    k.scale(3),
    k.area(),
    k.anchor("center"),
    k.pos(position),
    k.body({ jumpForce: 1700 }),
    {
      setControls(this: GameObj) {
        k.onButtonPress("jump", () => {
          if (this.isGrounded()) {
            this.play("jump");
            this.jump();
            k.play("jump", { volume: 0.5 });
          }
        });
      },
      setEvents(this: GameObj) {
        this.onGround(() => {
          this.play("run");
        });
      },
    },
  ]);
}

Let’s break it down.

import k from "./kaplayCtx";
import { Vec2, GameObj } from "kaplay";

We first import the KAPLAY context to be able to use the library’s functions in this file. We then import 2 types. Vec2 and GameObj. As you can see, KAPLAY offers TypeScript types you can use, making development in TypeScript smoother.

export function makeSonic(position: Vec2) {
  return k.add([
    k.sprite("sonic", { anim: "run" }),
    k.scale(3),
    k.area(),
    k.anchor("center"),
    k.pos(position),
    k.body({ jumpForce: 1700 }),
    {
      setControls(this: GameObj) {
        k.onButtonPress("jump", () => {
          if (this.isGrounded()) {
            this.play("jump");
            this.jump();
            k.play("jump", { volume: 0.5 });
          }
        });
      },
      setEvents(this: GameObj) {
        this.onGround(() => {
          this.play("run");
        });
      },
    },
  ]);
}

We then create a function who’s sole purpose is to create and return our Sonic game object. You can think of it as our constructor. We enable the function’s caller to set the position of the game object before it’s created. Positions in KAPLAY are Vec2s (stands for vector 2). It’s a data structure offered by KAPLAY which has two elements, x and y.

We use the sprite, scale, area, anchor, pos and body components to compose our game object.

Note that generally the pos comp can be passed the x and y coordinates as two distinct params or be passed a Vec2 containing both at once. In our code above, we opted for the latter while with our background and platforms game objects, we opted for the former.

In the case of the sprite comp, we not only display a sprite but set an animation. You might be wondering where does this “sonic” sprite and “run” anim comes from since we haven’t loaded anything like that at the moment? Indeed, we put the cart before the horse in this case. Let’s add the asset loading logic in main.ts. It will be a great opportunity to explain how animations work in KAPLAY.

How Animations Work in KAPLAY

In main.ts, add the following :

// place this behind last loadSprite call at the top of the file.
k.loadSprite("sonic", "graphics/sonic.png", {
  sliceX: 8,
  sliceY: 2,
  anims: {
    run: { from: 0, to: 7, loop: true, speed: 30 },
    jump: { from: 8, to: 15, loop: true, speed: 100 },
  },
});

The loadSprite function can take an object as an optional third param used for telling KAPLAY how to split an image into individual frames. When an image contains multiple sprites, it is often referred to as a spritesheet.

In our case, Sonic’s spritesheet looks like this.

We have a total of 16 frames which can be viewed as a grid of 2 rows and 8 columns. The object passed to loadSprite must first tell KAPLAY how to slice the image using the sliceX and sliceY properties. sliceX corresponds to the number of columns while sliceY corresponds to the number of rows.

Then, an anims object can be configured to set the animations we need and tell KAPLAY which animation is composed of which frames in our spritesheet.

run: { from: 0, to: 7, loop: true, speed: 30 },

If we take a look at the definition for the run animation, the from property holds the number of the starting frame of the anim while the to property holds the number of the last frame.

When KAPLAY slices the image into individual frames, it assigns a number to each of them starting from 0 and counting from left to right, top to bottom.

The loop property set to true makes the anim run indefinitely unless manually stopped while the speed property is used to set its frame rate.

The frame rate values used in the code above are arbitrary. I came up with these values based on what looked good during gameplay after tweaking values.

For more details on how animations work in KAPLAY check the post below.

k.sprite("sonic", { anim: "run" }),
k.scale(3),
k.area(),
k.anchor("center"),
k.pos(position),
k.body({ jumpForce: 1700 }),

Looking back at the components used for creating the Sonic game object in entities.ts, you’ll notice that the sprite comp takes as the first param the name of the image you want to display while the second param can be used to set the default running animation.

We use the scale comp to increase Sonic’s sprite size by 3. Which is what looked good during gameplay.

How Hitboxes Are Created in KAPLAY

The area comp is very useful because it allows us to easily create a hitbox for our player enabling us to call methods like onCollide, onCollideEnd, etc… useful for dealing with collisions.

In KAPLAY, just passing the area comp to the components array is enough to create a box surronding the player’s sprite if the sprite comp is also used. You might need in some cases to configure the position, width and height of the hitbox but in our game, this isn’t necessary at the moment. We will tackle this later.

Now that we have used the area comp, we can use the anchor comp to set the origin of our game object. By default, game objects are rendered starting from their top-left corner. This might not be very intuitive for game objects representing characters, that’s why I like using the anchor comp in those cases to set the center as the origin instead.

Finally, the body comp is used to give the game object a physics body allowing them to be affected by gravity. Using the body comp is crucial since it will give us access to the jump method which allows the game object to jump. In our body comp usage we set the game object’s jump force to be 1700. This is an arbitrary value which I arrived at after extensive testing during gameplay.

How to Add Methods to a Game Object

I explained earlier that a game object is composed of components. However, the add function which takes in an array of components can also be passed, to that same array, a JS object that you can use to set custom properties and methods for the resulting game object.

{
  setControls(this: GameObj) {
    k.onButtonPress("jump", () => {
      if (this.isGrounded()) {
        this.play("jump");
        this.jump();
        k.play("jump", { volume: 0.5 });
      }
    });
  },
  setEvents(this: GameObj) {
    this.onGround(() => {
      this.play("run");
    });
  },
},

We have an object containing two custom methods. The first one is used to set the player controls while the second is used to set what happens when Sonic hits the ground after jumping.

In these methods, we can use the this keyword, to access the sonic game object. In TypeScript, we need to specify what this is. This is done by creating a this param and typing it using the GameObj type definition imported from KAPLAY. When TypeScript is compiled to vanilla JS, this param will be removed.

setControls(this: GameObj) {
  k.onButtonPress("jump", () => {
    if (this.isGrounded()) {
      this.play("jump");
      this.jump();
      k.play("jump", { volume: 0.5 });
    }
  });
},

Taking a closer look at our custom setControls function, we can see that we call an onButtonPress KAPLAY function. As the name implies, this is used for handling when a specific button is pressed. It takes, as the first param, the name of the “button” you want to listen on. The second param is the function that will fire when that “button” is clicked.

If you remember, the “jump” “button” was defined in our KAPLAY context. This is where you need to define all the “buttons” you need for your game.

const k = kaplay({
  //... omitted for clarity
  buttons: {
    jump: {
      keyboard: ["space"],
      mouse: "left",
    },
  },
//... rest of the code omitted for clarity

if (this.isGrounded()) {
  this.play("jump");
  this.jump();
  k.play("jump", { volume: 0.5 });
}

Within our onButtonPress we check if the player is on top of a static game object using the isGrounded method which is available because Sonic has a body comp. At the moment, we haven’t defined any static game objects but we will create one later.

When the player is indeed grounded, we can set the jump animation to play, make the player jump with the jump method and finally play a jump sound using KAPLAY’s play function which is used to play audio.

Unfortunately, it’s very easy to confuse the play method which is used on a game object for playing animations VS the play function which is used for sound.

By the way, we need to load the jump sound in main.ts for it to work here. Add the following :

// place this behind last loadSprite call at the top of the file.
k.loadSound("jump", "sounds/Jump.wav");

The reason why we make sure the player is grounded before allowing any jump logic to run is so that the player can’t jump indefinitely making them able to fly away.

setEvents(this: GameObj) {
 this.onGround(() => {
   this.play("run");
 });
},

Our second custom method is used to set event logic. In KAPLAY, when a game object has the body component, you have access to the onGround event method. That method runs a function every time the player hits the ground (meaning collides on top of a static game object).

When the player jumps, the jump animation plays indefinitely. We want to switch back to the run animation as soon as the player lands back. The code above achieves this.

To reiterate, setControls and setEvents are custom methods we decided to create on our Sonic game object. They could have been named differently. We could have decided to only have one method that does all of the required logic. This is up to you when making your own KAPLAY games.

Adding Sonic to Our Game

Let’s create a floor on which to place Sonic.

Creating a Static Body as The Floor

Add the following code in main.ts :

// previous code omitted for clarity
// const platforms = [...]
  
// static body for the platforms
k.add([
  k.rect(1280, 200),
  k.opacity(0),
  k.pos(0, 641),
  k.area(),
  k.body({ isStatic: true }),
]);

// k.onUpdate(() => ...)
// rest of the code omitted for clarity

To create a static game object, you simply need to create a game object with an area and a body component. Within the body comp, set the isStatic property to true.

We use the rect comp to create a rectangular shape and we used the opacity comp set to 0 to make it invisible. We also don’t assign the game object to a constant since we don’t need a reference.

If you look at the webpage where the game is running (assuming your project is running), you will see that nothing has changed. However, if you activate the debug mode by pressing the f1 key (or fn+f1 keys on a Mac), you’ll see an outline representing the hitbox game object we just created.

For fun, you can try to put the opacity back to 1 and you’ll see a white rectangle at the bottom of the canvas.

Placing Sonic in The Game Scene

In main.ts, add the following :

// previous import statements omitted for clarity
import { makeSonic } from "./entities";

// ...

k.scene("game", () => {
  // ... platforms game object definition

  const sonic = makeSonic(k.vec2(100, 100));
  sonic.setControls();
  sonic.setEvents();
  
  // ... static body for the platforms game object definition
});

// ...

We call makeSonic and set a position using the vec2 KAPLAY function, assign the result to a constant called Sonic which enables us to call our custom methods setControls and setEvents, enabling our core player game logic. Everything should work now, but wait! Why is Sonic hanging in the air?

That’s because we haven’t set our game’s gravity. In KAPLAY, gravity is set per scene using the setGravity function and passing to it a number determining how strong it will be.

Add the following code in our “game” scene definition :

k.scene("game", () => {
  k.setGravity(3100);
  // ...
});
// ...

I came up with 3100 after trial and error. You need to test during gameplay to see if the jump is floaty or not and that’s how I came up with this value.

Now, if you run the project. You should see Sonic initially fall on the platforms and immediately start running. You can now jump and when you do, Sonic should curl into a ball and you should hear a jump sound. However, as soon as he hits the ground, the run animation should be the one playing.

Conclusion

Up to this point we covered a lot of KAPLAY specific concepts and we made quite a bit of progress on our Sonic game. However, there’s still work to do. In the next part of the tutorial we will :

• Add rings for Sonic to collect.

• Implement a scoring system.

• Add Motobug enemies that Sonic can jump on for more rings.

• Implement a combo system allowing Sonic to earn extra rings by continuously jumping on Motobugs before hitting the ground again.

Update : Part 2 is now available!

In my opinion, the most approachable way to get into game development is to make small games. However, making the usual Pong or Flappy bird clone is boring.

In this post, I’ll share where I find inspiration for building interesting small games.

Playing PICO-8 Games

PICO-8 is a fantasy console, meaning a console that doesn’t actually exist. In practice it’s a virtual machine that has a bunch of artificial limitations (number of colors it can display, resolution, limited sprites, etc…).

There are two components to it. The first one is for developers where you can develop your game entirely in PICO-8 using the lua programming language. It has a built-in code editor, sprite editor, level editor and sound editor.

Since this fantasy console is so limited in what it can do, developers can easily avoid making games that are too big in scope.

The second component is the console aspect, where you can play games made in PICO-8.

While I think limitations breeds creativity, I think PICO-8’s limitations are a bit too much for me as a developer, however, I think it’s worth playing games made in it. You’ll get very inspired by how creative these small games are.

I recommend installing the P8GO app which allows you to discover PICO-8 games in a TikTok style app, allowing you to cover a lot of games quickly.

Revisiting Old Games

There are a lot of games released in the past that are easy to remake today. I recommend looking up and trying old arcade, NES and Gameboy games. A good exercise is to try remaking them while simplifying or improving the user experience since many of these games were obtuse as gaming was relatively young back then. A lot of the established quality of life features we’re used to today weren’t common.

Take an Aspect of An Existing Game and Make a Small Game About it

In the startup world, you’ll often see successful businesses emerge by taking one of the many features an establish company already has and focusing exclusively on building that one feature as their product. You can take the same approach in game dev.

Example 1

In The Legend of Zelda Link’s Awakening, there is a part of the game where you need to do a trading sequence. Meaning, exchange an item with an NPC to get another item you can exchange with another NPC until you obtain the item you need.

What if you made a game that was exclusively about trading things with NPCs to get an item the player needs?

While that might not sound particularly fun, you can always take inspiration from things outside of game dev to spice up your game concept.

For example, Rayan Trahan, a popular YouTuber, made a series called the penny challenge. He starts with a penny and needs to cross through America using only that as his starting budget. The YouTuber then proceeds to buy, sell and trade items enabling them to gradually increase their wealth so they can pay for transportation and other expenses to achieve their goal.

Now, let’s modify the game idea a bit.

What if you made a game where the player starts in a small island/town and wants to leave that town. To do so, they must buy an expensive ticket for a cruise that will enable them to leave. However, they’re broke and need to explore the town for items, and trade them with NPCs, until they make enough money to buy the ticket and leave.

Add to this, challenging aspects, like some NPCs only being interested in certain items, and you’ve got a nice little game. You can add a bit of randomness with which NPC wants what and this will make each run different allowing your game to be highly replayable.

Example 2

In the popular game franchise Pokémon, you often need to pass by a Pokémart to buy various items useful in your adventure. What if you made a game solely about managing a Pokémart?

You don’t have to use the Pokémon IP, you could replace it with your own monster catching IP. Instead of selling Pokéballs, you would sell CaptureCubes or something to that effect.

The whole game would take place within the mart. Every time a new customer enters, they can either buy from your inventory or you can buy from them. Which could be your only way of getting certain items in demand by other customers. Your goal is to stay in business since you have expenses, while keeping customers happy by having the items they need so that they keep coming to your mart.

I could go on, but I think you get the point.

Look for Inspiration Outside of Gaming

In the first example of the previous section, I mentioned taking inspiration from a YouTuber’s video series. This is an example of taking inspiration from outside of gaming and I’d argue that the truely novel ideas can be found there.

What if you made a game about managing a library? A game about being a moderator of a social media website? A game about being a lumberjack? A game about managing a retro handled company? What if you made a game based on a book, how would you adapt it so that the game is fun? The list goes on.

Conclusion

In the end, there are a lot of ways to find good small game ideas. In this post, I shared what the inspiration sources I use. If you want to learn game development, web development or game developement using web dev tools, I recommend subscribing to not miss out on future posts and tutorials.

Thanks for reading!

Subscribe now

In the meantime, you can check out my previous content.

I recently published a beginner React.js tutorial on building a game search app as a series of free substack posts.

However, I would like to announce that you can now purchase the tutorial as a nicely formatted PDF.

The advantage of the PDF is that you have everything in one place and it’s nicely formatted with an easy to navigate table of contents. It’s 5$ and you can buy it here.

Here is a preview showcasing how the PDF looks like.

In the previous part (Here are links to part 1 and part 2), we finished setting up the logic to fetch data from our backend. Now it’s time to display the data in a nice looking UI.

Table of Contents

• Creating The Game Card Component

  • Conditional Rendering in React

  • How to Render Lists in React

• Rendering a List of Game Cards

• Handling Edge Cases and Improving The User Experience

  • Displaying Error Messages in The UI

  • Adding a Loading Spinner

• Building The Game Details Component

  • Creating a New API Endpoint to Fetch More Data

  • Rendering The Game Details Component

• Creating The Screenshot Carousel

• Conclusion

Creating The Game Card Component

After the user makes a search, we want to display a list of relevant games that will be rendered as a grid of cards where each card contains the game’s title, genres, cover image and the time it takes to complete the game if the data is available.

The first step to achieve this is to build a reusable game card component. Inside the components folder, create a file called GameCard.jsx.

src
|- components
      |- GameCard.jsx

Within that file, add the following code :

export default function GameCard({
  coverLink,
  name,
  playtime,
  genres,
  onClick,
}) {
  return (
    <div className="flex-col relative" onClick={onClick}>
      <img
        src={coverLink}
        loading="lazy"
        className="w-full h-40 object-cover rounded-md"
      />

      <h1 className="p-2 text-gray-300 text-lg">{name}</h1>
      {playtime !== 0 && (
        <div className="flex items-center gap-2 mx-2 bg-gray-800 p-2 absolute top-2 right-0 rounded-md">
          <img
            src="./clock-fill.svg"
            className="text-gray-300 max-w-xs max-h-xs"
          />
          <p className=" text-gray-300 text-sm whitespace-nowrap">
            {playtime} Hours
          </p>
        </div>
      )}

      <li className="flex flex-row flex-wrap gap-2 m-2 mt-auto">
        {genres.map((genre) => (
          <ul className="genre-pill" key={genre.name}>
            {genre.name}
          </ul>
        ))}
      </li>
    </div>
  );
}

We create a component with 5 props.

• coverLink : The link of the cover image.

• name : The name of the game.

• playtime : How long the game takes to beat.

• genres : An array containing the game’s genres.

• onClick : A function that will run when the user clicks on a card.

Let’s break down the JSX returned by the component.

<div className="flex-col relative" onClick={onClick}>

We the return a div that acts as the card container. We set is as a flex container and make it relative so that within, we will be able to place the playtime indicator at the top-right of the card using absolute positioning. We then set the onClick function passed as a prop to trigger when the container is clicked.

<img
  src={coverLink}
  className="w-full h-40 object-cover rounded-md"
/>

We display the game’s cover using a simple img tag. First, the image is set to take the full available width with w-full . The height is set to 40 Tailwind units using h-40.

The object-cover Tailwind class is used to render the image in its original aspect ratio while still fitting within the width and height of the img tag. rounded-md stands for rounded medium and makes the corner of the image noticeably rounded.

 <h1 className="p-2 text-gray-300 text-lg">{name}</h1>

This h1 tag is used to display the game’s name.

{playtime !== 0 && (
        <div className="flex items-center gap-2 mx-2 bg-gray-800 p-2 absolute top-2 right-0 rounded-md">
          <img
            src="./clock-fill.svg"
            className="text-gray-300 max-w-xs max-h-xs"
          />
          <p className=" text-gray-300 text-sm whitespace-nowrap">
            {playtime} Hours
          </p>
        </div>
)}

We use conditional rendering to render the playtime indicator only if the playtime is above 0 hours. Usually, if it’s 0 then that means the playtime data for this game isn’t available. The RAWG API returns 0 in that case.

Using absolute positioning we’re able to place the indicator at the top-right corner of the game card by using absolute top-2 right-0.

Conditional Rendering in React

There are many ways to achieve conditional rendering in React. Here are a few examples.

First example with an if statement.

function myComp() {
  if (condition) {
    return (
      <div>
        <h1>B</h1>
      </div>
    );
  }

  return (
    <div>
      <h1>A</h1>
    </div>
  );
}

Second example with a boolean expression.

function myComp() {
   return (
     <div>
       {condition && <h1>B</h1>}
       {!condition && <h1>A</h1>}
     </div>
   );
}

Third example, with a ternary operator.

function myComp() {
   return (
     <div>
       {condition ? <h1>B</h1> : <h1>A</h1>}
     </div>
   );
}

If you want to achieve conditional rendering within JSX you can’t use an if statement and are forced to use either a boolean expression or a ternary operator. Between using a boolean expression or a ternary operator in the example above, the latter is better since we display “B” in the case the condition is true and “A” otherwise.

{playtime !== 0 && (... rest of the code)}

However, in our game card component we display the playtime indicator only if its value is above 0 and nothing otherwise. Therefore, the boolean expression is more fitting for our use case.

<li className="flex flex-row flex-wrap gap-2 m-2 mt-auto">
 {genres.map((genre) => (
    <ul className="genre-pill" key={genre.name}>
      {genre.name}
    </ul>
  ))}
</li>

Finally, we display the genres of the game. There can be more than one, that’s why we’re rendering this section as a list of items. Now has come the time to understand how lists are rendered in React.

Note that the class genre-pill is a custom class and you need to add it to your index.css file for it to work.

.genre-pill {
  @apply bg-red-800 rounded-full px-2 text-gray-300 text-sm;
}

How to Render Lists in React

It often occurs when working on Web UIs that you want to render multiple elements at once. For example, you want to render a list of search results, in our case, a bunch of game cards.

In React, you can achieve this by using the JavaScript .map function to iterate over an array and for each element return some JSX. At a basic level, it looks like this.

function myComp() {
  const lines = ["Hello World!", "Foo", "Bar"];

  return (
    <ul>
      {lines.map((line) => <li>{line}</li>)}
    </ul>
  );
}

 {lines.map((line) => <li>{line}</li>)}

However, there is something missing in the code above. When rendering multiple elements, the rendered JSX elements need to be assigned a key. This is to enable React to establish a relationship between array elements and the corresponding JSX element. This becomes very important if items of the list are later added or removed. The key enables React to make the correct updates to the DOM.

You might come across React code using the index of the element as the key.

 {lines.map((line, index) => <li key={index}>{line}</li>)}

This is to be avoided when the array can change later down the line. For example, if the elements of the array are sorted in a different order, the relationship between the index and the JSX element will be broken.

To avoid this from happening, it’s usually best to use a consistent but unique key. Consistent in the sense that the key doesn’t change from render to render and unique so that no two elements in the list have the same key.

In our example above, the only key that would best fulfill these two conditions are the lines themselves.

{lines.map((line) => <li key={line}>{line}</li>)}

If we assume that the data you want to display comes from a source that you control, you could have decided to assign a unique id for each item before sending the data to the client.

For example, let’s assume that each line of our lines array will have an id. You would have something like this :

[{id: "u90909dfj89", content: "Hello World"}, ...]

You would use the id as the key.

{lines.map((line) => <li key={line.id}>{line.content}</li>)}

Alternatively, with destructuring you would do :

{lines.map(({id, content}) => <li key={id}>{content}</li>)}

For our genres, since the genre name is unique, we use the name for both the content of the list item and the key.

Rendering a List of Game Cards

Now that we have finished the game card component, let’s use it in App.jsx to display relevant games when the search feature is used.

Add the following code :

// previous code omitted for clarity
import GameCard from "./components/GameCard";

export default function App() {
  // previous code omitted for clarity

  const { data, loading, fetchData, error, reset } = useFetch(() =>
    fetchGames({ query: searchQuery })
  );

  // code omitted for clarity

  // second useEffect is no longer needed. This was just for testing purposes
  // useEffect(() => {
  //  if (data) console.log(data);
  // }, [data]);

  return (
    <main className="w-full p-2 flex flex-col items-center">
      {/* code omitted for clarity */}
      <div className="w-full max-w-4xl">
        <Search
          query={searchQuery}
          onChange={(e) => setSearchQuery(e.target.value)}
        />
        <div className="w-full">
          {data && (
            <div className="grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-3">
              {data.results.map(
                (game) =>
                  game.added > 30 && (
                    <GameCard
                      key={game.slug}
                      name={game.name}
                      coverLink={game.background_image}
                      playtime={game.playtime}
                      genres={game.genres}
                      onClick={() => {
                        console.log("test");
                      }}
                    />
                  )
              )}
            </div>
          )}
        </div>
      </div>
    </main>
  );
}

Let’s break it down.

{data && (
  <div className="grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-3">
    {data.results.map(
      (game) =>
        game.added > 30 && (
          <GameCard
            key={game.slug}
            name={game.name}
            coverLink={game.background_image}
            playtime={game.playtime}
            genres={game.genres}
            onClick={() => {
              // TODO
              console.log("test");
            }}
          />
         )
       )}
  </div>
)}

We only render the game cards if the data is available. In that case, we first render a div which acts as a container for all game cards and is going to be displayed as a CSS grid.

grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-3

• grid : sets the div as a grid container.

• grid-cols-1 : sets the grid to have 1 column only.

• gap-5 : sets a gap of 5 units between each elements in the grid.

• sm:grid-cols-2 : sets the number of columns of the grid to be 2 on smaller screens and beyond. sm is a media query in Tailwind.

• lg:grid-cols-3 : sets the number of columns of the grid to be 3 on larger screens and beyond. lg is also a media query in Tailwind.
  

{data.results.map(
  (game) =>
    game.added > 30 && (
      <GameCard
        key={game.slug}
        name={game.name}
        coverLink={game.background_image}
        playtime={game.playtime}
        genres={game.genres}
        onClick={() => {
          // TODO
          console.log("test");
        }}
      />
    )
  )
}

We get the game cards data by doing data.results which returns an array. We then map over it to render each game card.

Before rendering a game card we make sure that the game has been added at least more than 30 times. The reason we’re doing this is that the RAWG API has the added property which determines how much a game was added. It doesn’t specify what added is exactly but I’ve noticed that if you just render what ever the array has you’ll often find yourself displaying cheap fangames and clones along side more legit titles. To show the best quality results as possible, I have figured out through testing that a game must have been added at least 30 times to be considered “legit”.

As mentioned previously when rendering an array in React you must provide a key for each element. Here is no exception. However, you might be wondering if we have to define a prop called key on the GameCard component before passing to it a key since it’s custom made and not a native JSX element? Fortunately, you don’t have to, it’s taken care of automatically by React.

Since the RAWG API returns a slug for each game, this will act as our unique key since it never changes for a specific game and is unique.

Now that we have added our game card list rendering logic, let’s test it out. Make sure to have your backend and frontend running with node index.js and npm run dev respectively.

You should have the following results.

Handling Edge Cases and Improving The User Experience

While we were able to successfully display relevant results when a user makes a query there are still edge cases we aren’t handling.

Displaying Error Messages in The UI

For example, what should be shown to the user if there are no games relevant to what they searched for?

In that case nothing is shown which isn’t a great user experience. To fix this, let’s add a message that will be displayed when no relevant search results are found.

Modifiy the code we had previously like shown below.

<div className="w-full">
  {data && (
    <>
      <div className="grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-3">
        {data.results.map(
          (game) =>
            game.added > 30 && (
              <GameCard
                key={game.slug}
                name={game.name}
                coverLink={game.background_image}
                playtime={game.playtime}
                genres={game.genres}
                onClick={() => {
                  console.log("test");
                }}
              />
          )
        )}
       </div>
       {data.results.length === 0 && (
         <div className="w-full flex flex-col justify-center items-center">
           <img src="./no-results-found.png" className="size-52" />
           <p className="text-gray-300 text-2xl">No games found!</p>
         </div>
        )}
    </>
  )}
</div>

<></> is called a React fragment. This is useful when you don’t want to create an unnecessary div to wrap two or more elements at the same level. In our case we want the JSX for the search results and the JSX for the “No games found!” message to be both children of the container div having the className w-full. There is no need to wrap them under an additional div.

Now let’s test things out.

As you can see, the message showed up.

There’s still another edge case we haven’t taken into account. What if, for some reason, the app fails to retrieve data from the backend? Currently we show nothing in that case. However, the wise thing to do is to have some kind of error message displayed to the user.

Since this error message is going to have the same structure as the one we used for the “No games found!” message, let’s create a reusable component in the components folder. Create the file ErrorMessage.jsx with the following code.

export default function ErrorMessage({ message }) {
  return (
    <div className="w-full  flex flex-col justify-center items-center">
      <img src="./no-results-found.png" className="size-52" />
      <p className="text-gray-300 text-2xl">{message}</p>
    </div>
  );
}

Now, we can use this component in App.jsx. Import the ErrorMessage component at the top of the file.

import ErrorMessage from "./components/ErrorMessage";

Then, replace the JSX we used for the “No games found!” message.

From :

{data.results.length === 0 && (
  <div className="w-full flex flex-col justify-center items-center">
    <img src="./no-results-found.png" className="size-52" />
    <p className="text-gray-300 text-2xl">No games found!</p>
  </div>
)}

to :

{data.results.length === 0 && (
  <ErrorMessage message={"No games found!"} />
)}

Let’s use the same component to display an error message when the apps fail to retrieve the data from the backend.

// previous code omitted for clarity
<div className="w-full">
  {data && (...)}
  {error && <ErrorMessage message={"Network Error Occured!"} />}
</div>

Now, when a network error occurs, you’ll get the following UI.

Adding a Loading Spinner

Another thing to improve upon is the fact that we give no indication to the user that the app is loading search results. Let’s add a spinner so that user doesn’t think the app has crashed.

Under the components folder create a file called Spinner.jsx and add the following code :

export default function Spinner() {
  return (
    <div role="status">
      <svg
        aria-hidden="true"
        className="w-8 h-8 text-gray-200 animate-spin dark:text-gray-600 fill-blue-500"
        viewBox="0 0 100 101"
        fill="none"
        xmlns="http://www.w3.org/2000/svg"
      >
        <path
          d="M100 50.5908C100 78.2051 77.6142 100.591 50 100.591C22.3858 100.591 0 78.2051 0 50.5908C0 22.9766 22.3858 0.59082 50 0.59082C77.6142 0.59082 100 22.9766 100 50.5908ZM9.08144 50.5908C9.08144 73.1895 27.4013 91.5094 50 91.5094C72.5987 91.5094 90.9186 73.1895 90.9186 50.5908C90.9186 27.9921 72.5987 9.67226 50 9.67226C27.4013 9.67226 9.08144 27.9921 9.08144 50.5908Z"
          fill="currentColor"
        />
        <path
          d="M93.9676 39.0409C96.393 38.4038 97.8624 35.9116 97.0079 33.5539C95.2932 28.8227 92.871 24.3692 89.8167 20.348C85.8452 15.1192 80.8826 10.7238 75.2124 7.41289C69.5422 4.10194 63.2754 1.94025 56.7698 1.05124C51.7666 0.367541 46.6976 0.446843 41.7345 1.27873C39.2613 1.69328 37.813 4.19778 38.4501 6.62326C39.0873 9.04874 41.5694 10.4717 44.0505 10.1071C47.8511 9.54855 51.7191 9.52689 55.5402 10.0491C60.8642 10.7766 65.9928 12.5457 70.6331 15.2552C75.2735 17.9648 79.3347 21.5619 82.5849 25.841C84.9175 28.9121 86.7997 32.2913 88.1811 35.8758C89.083 38.2158 91.5421 39.6781 93.9676 39.0409Z"
          fill="currentFill"
        />
      </svg>
      <span className="sr-only">Loading...</span>
    </div>
  );
}

This component is based upon the loading spinner example found here. Most of it is SVG code. I will not explain how SVG work because it’s out of the scope of this tutorial. Let’s just use that spinner as is in our app.

In App.jsx, add the following code :

// previous code omitted for clarity
import Spinner from "./components/Spinner";

Then, modify our existing code where we display the search results :

<div className="w-full">
  {!loading ? (
    <>
      <div className="grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-3">
        {data?.results.map(
          (game) =>
            game.added > 30 && (
              <GameCard
                key={game.slug}
                name={game.name}
                coverLink={game.background_image}
                playtime={game.playtime}
                genres={game.genres}
                onClick={() => {
                  console.log("test");
                }}
              />
            )
         )}
       </div>
       {data?.results.length === 0 && (
         <ErrorMessage message={"No games found!"} />
       )}
    </>
   ) : (
    <div className="flex justify-center">
      <Spinner />
    </div>
  )}
  {error && <ErrorMessage message={"Network Error Occurred!"} />}
</div>

You’ll notice that we now have a ternary operator that determines whenever or not to show the spinner. If we aren’t in a loading state we render the grid or the error message. We use data? with the question mark as to only attempt to access the results property of the data object if it’s available.

Now, let’s test it out.

Building The Game Details Component

The final part of this project consists in building the game details component which is a component that will display a dedicated section for a specific game after having clicked on its game card. In a production app, you would probably use a router like React Router and make it display as its own separate page.

However, I wanted to limit the use of third-party libraries, so I opted for displaying a component on the same page instead.

Creating a New API Endpoint to Fetch More Data

Before we build that component, we need to write a new API endpoint in our backend to fetch data specific to a game. This endpoint will return a detailed description of the game. This wasn’t provided by the previous endpoint we had.

In your backend, add the following endpoint to your index.js file.

app.get("/api/game", async (req, res) => {
  const { gameSlug } = req.query;

  try {
    const response = await fetch(
      `https://api.rawg.io/api/games/${gameSlug}?key=${API_KEY}`,
      {
        method: "GET",
        headers: {
          "Content-Type": "application/json",
        },
      }
    );

    if (!response.ok) {
      throw new Error("Failed to fetch data from external API");
    }

    const data = await response.json();

    return res.json(data);
  } catch (error) {
    console.error("Error fetching data from API:", error);
    return res
      .status(500)
      .json({ error: "Failed to fetch data from external API" });
  }
});

The first API endpoint returns, amongst other things, the game’s slug which we can use to query this second endpoint by passing it as a param.

Now restart the backend by doing Ctrl+C and running the command node index.js. Then, in our frontend, in the api.js file, add the following code :

// previous code omitted for clarity

export async function fetchGameData({ gameSlug }) {
  const response = await fetch(`${API_ENDPOINT}/game?gameSlug=${gameSlug}`);
  return await response.json();
}

Finally, in the components folder, create a new file called GameDetails.jsx and add the following code.

import { useEffect } from "react";
import useFetch from "../hooks/useFetch";
import { fetchGameData } from "../api";

export default function GameDetails({ currentGame, goBack }) {

   const { data, loading, fetchData, error, reset } = useFetch(() =>
     fetchGameData({ gameSlug: currentGame.slug })
   );

   useEffect(() => {
    (async () => {
      await fetchData();
    })();
   }, []);


   return (<section></section>);
}

We started things simple, by writing the logic to fetch the relevant data as soon as the component is rendered. We pass two props to the component. currentGame which is an object that contains the data previously fetched for a specific game. It contains the game’s slug (which is its id), genres, title, etc… We use the slug to fetch more data (the game’s detailed description).

The second prop is a function used to enable the user to go back to the search results if they wish to do so. Like mentioned earlier, in a production app, use something like React Router so that the user can use the back button of their browser to go back. This is called navigation and isn’t built into React by default, underlining the need for a third party library.

Our backend will return a description of the game and is formatted as a single long string. If we render it as is, it will not look good in the UI. That’s why we need to add the following utility function. Place it above where the GameDetails component is defined.

// import statements should be here

function createParagraphs(inputString) {
  // Split the string into sentences using regex to match sentence-ending punctuation (., !, ?)
  const sentences = inputString.match(/[^.!?]+[.!?]+/g) || [];

  // Initialize an array to hold the paragraphs
  const paragraphs = [];

  // Loop through the sentences and create paragraphs with a max of 3 sentences
  for (let i = 0; i < sentences.length; i += 3) {
    // Join the next 3 sentences to form a paragraph
    const paragraph = sentences
      .slice(i, i + 3)
      .join(" ")
      .trim();
    paragraphs.push(paragraph);
  }

  return paragraphs;
}

export default function GameDetails({ currentGame, goBack }) {
// rest of the code omitted for clarity

Now that we have this, we can modify our GameDetails component like so.

import { useEffect, useState } from "react";
// ... other import statements

export default function GameDetails({ currentGame, goBack }) {
   const [description, setDescription] = useState([]);

   const { data, loading, fetchData, error, reset } = useFetch(() =>
     fetchGameData({ gameSlug: currentGame.slug })
   );

   useEffect(() => {
    (async () => {
      await fetchData();
    })();
   }, []);

   
   useEffect(() => {
    if (data) {
      const rawDescription = data.description_raw;
      const paragraphs = createParagraphs(rawDescription);

      setDescription(paragraphs);
    }
   }, [data]);
   


   return (<section></section>);
}

We create a state variable for holding the description and use a second useEffect to split the game’s description into paragraphs as soon as the data is available.

Let’s add more JSX but before, import the Spinner component we wrote previously.

import Spinner from "./Spinner";

// previous code omitted for clarity
<section>
  <button className="main-button flex" onClick={goBack}>
    <img src="./back-arrow.svg" /> <span className="mx-2">Go Back</span>
  </button>

  {!data ? (
    <div className="flex justify-center mt-4">
      <Spinner />
    </div>
  ) : (
    <div className="mt-4">
      <div className="w-full relative">
        <div className="absolute inset-0 bg-gradient-to-b from-black via-transparent to-transparent opacity-80"></div>
        <h1 className="text-gray-200 text-2xl absolute top-5 left-5">
          {currentGame.name}
        </h1>
        <img
          className="w-full h-40 object-cover rounded-md"
          src={currentGame.background_image}
        />
      </div>
      <div>
       
        <div className="text-gray-300">
          {description.map((paragraph, index) => (
            <p className="mt-2" key={index}>
              {paragraph}
            </p>
          ))}
        </div>
        

        <div className="w-full flex flex-col items-center p-4 h-96">
             TODO: Screenshot Carousel
        </div>

        <div className="grid grid-cols-2 py-4">
          <div className="flex flex-col">
            <h2 className="text-gray-300 text-xl">Genres</h2>
            <ul className="flex flex-wrap gap-2 py-2">
              {currentGame.genres.map((genre) => (
                <li className="genre-pill" key={genre.name}>
                  {genre.name}
                </li>
              ))}
            </ul>
            <h2 className="text-gray-300 text-xl">Platforms</h2>
            <ul className="flex flex-wrap gap-2 py-2">
              {currentGame.platforms.map((platform) => (
                <li key={platform.platform.name} className="platform-pill">
                  {platform.platform.name}
                </li>
              ))}
            </ul>
          </div>
          <div className="flex justify-center items-center">
            <button
              className="main-button flex items-center"
              onClick={() =>
                window.open(
                  `https://google.com/search?q=where+to+buy+${currentGame.name}`,
                  "_blank"
                )
              }>
               <span className="ml-4 mr-2">Purchase</span>
               <img src="./shopping-cart.svg" className="size-6 mr-4" />
             </button>
          </div>
        </div>
      </div>
    </div>
  )}
</section>

Let’s break it down.

<button className="main-button flex" onClick={goBack}>
    <img src="./back-arrow.svg" /> <span className="mx-2">Go Back</span>
</button>

This is the button placed at the top of the component allowing user’s to go back to the search results if they wish to do so. You’ll notice that we’re using a custom class called main-button. Add it to you index.css file. Also, add the platform-pill custom class which is used for displaying the various platforms the game can be played on as pill shaped blue “pills”.

.main-button {
  @apply bg-blue-400 rounded-md p-2;
}

.platform-pill {
  @apply bg-blue-800 rounded-full px-2 text-gray-300 text-sm;
}

{loading ? (
    <div className="flex justify-center mt-4">
      <Spinner />
    </div>
) : (...)}

We then use a ternary operator, to show a loading spinner while we’re fetching the description data for the game. Once loading is completed, we render some JSX containing a banner with the game’s cover and name followed by the game’s description rendered in multiple paragraphs. Then, we will render a screenshot carousel that will be its own separate component (We will write the code for it later) and finally, we render the list of genres of the game and the various platform you can play it on. Additionally, we render a button that will open up a google page with a query to determine where the user can purchase the game.

Rendering The Game Details Component

Before proceeding with the screenshot carousel component, let’s first try to render the GameDetails component when a user clicks on a game card in the search results.

Add the following code to App.jsx.

import GameDetails from "./components/GameDetails";

function App() {
  // ... code omitted for clarity

  const [showGameDetails, setShowGameDetails] = useState(false);
  const [currentGame, setCurrentGame] = useState(null);

  // ...
 
  return (
       // ...
       <div className="w-full">
           {!loading && !showGameDetails ? 
             (...) : 
             showGameDetails ?  (
            <GameDetails
              currentGame={currentGame}
              goBack={() => {
                setShowGameDetails(false);
                setCurrentGame(null);
              }}
            />
          ) : (
            <div className="flex justify-center">
              <Spinner />
            </div>
          )}
       </div>
       // ...

  )

Then, in the onClick of the GameCard components in App.jsx add the following.

{data.results.map(
  (game) =>
    game.added > 30 && (
      <GameCard
        key={game.slug}
        name={game.name}
        coverLink={game.background_image}
        playtime={game.playtime}
        genres={game.genres}
        onClick={() => {
          setCurrentGame(game); // <--
          setShowGameDetails(true); // <--
        }}
      />
    )
)}

Now, if you run the app (make sure to restart the backend and the frontend) you should have the following results.

Creating The Screenshot Carousel

The last component of this project consists in a screenshot carousel. In the components folder, create a file named ScreenshotCarousel.jsx and add the following code :

import { useState, useEffect } from "react";

export default function ScreenshotCarousel({ screenshots }) {
  const [currentScreenshotIndex, setCurrentScreenshotIndex] = useState(0);

  useEffect(() => {
    // trick to preload the images
    for (const screenshot of screenshots) {
      const img = new Image();
      img.src = screenshot.image;
    }
  }, []);

  return (
    <div
      className="bg-gray-800 rounded-lg w-full h-full max-h-96 overflow-hidden relative"
    >
      <button
        className="bg-gray-200 rounded-full p-4 absolute top-40 right-5 shadow-gray-700 shadow-xl z-10"
        onClick={() => {
          setCurrentScreenshotIndex((currentScreenshotIndex) => {
            if (currentScreenshotIndex < screenshots.length - 1) {
              return currentScreenshotIndex + 1;
            }

            return 0;
          });
        }}
      ><img src="./arrow-right.svg" /></button>
      <button
        className="bg-gray-200 rounded-full p-4 absolute top-40 left-5 shadow-gray-700 shadow-xl z-10"
        onClick={() => {
          setCurrentScreenshotIndex((currentScreenshotIndex) => {
            if (currentScreenshotIndex > 0) {
              return currentScreenshotIndex - 1;
            }

            return screenshots.length - 1;
          });
        }}
      ><img src="./arrow-left.svg" /></button>

      <img
        className="object-cover w-full h-full absolute z-0 blur-md opacity-50"
        src={screenshots[currentScreenshotIndex].image}
      />
      <img
        className="object-contain w-full h-full absolute"
        src={screenshots[currentScreenshotIndex].image}
      />

      <span className="bg-gray-900 rounded-full px-4 py-1 text-gray-300 text-xs absolute right-2 top-2 shadow-gray-700 shadow-xl">
        {currentScreenshotIndex + 1} / {screenshots.length}
      </span>
    </div>
  );
}

Let’s break it down.

export default function ScreenshotCarousel({ screenshots }) {

We set a screenshots prop which will hold the array containing all screenshots of a given game.

const [currentScreenshotIndex, setCurrentScreenshotIndex] = useState(0);

useEffect(() => {
// trick to preload the images
  for (const screenshot of screenshots) {
    const img = new Image();
    img.src = screenshot.image;
  }
}, []);

We first declared a state variable for holding the index of the current screenshot being displayed.

We use a useEffect to preload all the screenshots. This is useful, so that when the user clicks on the arrow to look at the next image, they will see it instantly and won’t have to wait for it to load.

<div
  className="bg-gray-800 rounded-lg w-full h-full max-h-96 overflow-hidden relative"
>

We return a div that acts as the screenshot carousel’s container. It has a background of bg-gray-800, rounded corners with rounded-lg (stands for rounded large), takes the full width available of the parent element with w-full, takes the full height but caps out at 96 units with h-full and max-h-96, prevents overflowing with overflow-hidden and is set to relative so we can absolute position the arrows.

<button
  className="bg-gray-200 rounded-full p-4 absolute top-40 right-5 shadow-gray-700 shadow-xl z-10"
  onClick={() => {
    setCurrentScreenshotIndex((currentScreenshotIndex) => {
      if (currentScreenshotIndex < screenshots.length - 1) {
        return currentScreenshotIndex + 1;
      }

      return 0;
    });
  }}
><img src="./arrow-right.svg" /></button>
<button
  className="bg-gray-200 rounded-full p-4 absolute top-40 left-5 shadow-gray-700 shadow-xl z-10"
  onClick={() => {
    setCurrentScreenshotIndex((currentScreenshotIndex) => {
      if (currentScreenshotIndex > 0) {
        return currentScreenshotIndex - 1;
      }

      return screenshots.length - 1;
    });
  }}
><img src="./arrow-left.svg" /></button>  

Here, we added our two arrow buttons that allow the user to move back and forth. For both buttons their onClick handlers updates the screenshot index properly by making sure that we don’t go out of the bounds of the screenshots array.

Once the screenshot index is set, the carousel will re-render to display the correct image which is set here.

<img
  className="object-cover w-full h-full absolute z-0 blur-md opacity-50"
  src={screenshots[currentScreenshotIndex].image}
/>
<img
  className="object-contain w-full h-full absolute"
  src={screenshots[currentScreenshotIndex].image}
/>

The reason we have two img tags, is that the first one will act as the background and will be blurred while the second img tag displays the screenshot visible by the user.

We use object-cover for the first tag, so that the image will take all the available space in the container and we use object-contain in the second image so that the image retain its aspect ratio. Therefore, the user will be able to see the full screenshot without having part of it cropped out.

<span className="bg-gray-900 rounded-full px-4 py-1 text-gray-300 text-xs absolute right-2 top-2 shadow-gray-700 shadow-xl">
  {currentScreenshotIndex + 1} / {screenshots.length}
</span>

Finally, we have a span tag which will render as a top-right indicator of which screenshot you’re currently viewing.

Now, that we have finished the carousel component, let’s add it in GameDetails.jsx.

First import the carousel at the top of the file.

// previous code omitted for clarity
import ScreenshotCarousel from "./ScreenshotCarousel";

Then, replace this :

<div className="w-full flex flex-col items-center p-4 h-96">
  TODO: Screenshot Carousel
</div>

With :

<div className="w-full flex flex-col items-center p-4 h-96">
  {currentGame.short_screenshots.length !== 0 && (
    <ScreenshotCarousel
      screenshots={currentGame.short_screenshots.slice(0)} // exclude the first screenshot since it's the same as the cover
    />
  )}
</div>

Now, if you run the project, you should get the following.

Conclusion

You have finished your first React project! I have not touched on deployment (there are many different ways to go about it and plenty of tutorials online) and other React topics but I hope this was a good introduction.

Now that you have a basic foundation in React, you can start building your own projects and fill in your knowledge gaps using Google or taking a look at the official React docs.

You might be interested in game development? You can check out this next.

Since we have mostly finished our setup in the previous part of this tutorial (You can read part 1 here). We’re ready to start working on the search page of the app which is the main page of the application.

In that page, the user should be able to use the search bar to search for a given game title or franchise and the app should call our backend which will call the RAWG API to retrieve a list of relevant games. Then, the app should display those games as cards containing a cover, a title, genres and how long it takes to beat the game if that data is available.

Now that you know what we need to build, let’s get started. I’ll introduce relevant concepts as we go.

Table of Contents

• How is React Initialized in Our Project?

• What are React Components?

• React VS React-DOM

• Making Our First React Component

• Creating The Search Component

  • What Are Props in React?

  • What Are Hooks in React?

    • The useState Hook

• Setting Our Backend to Enable Search Requests to The RAWG API

  • Setting Up Express

  • Defining The /api/games Route

• Fetching Search Data on The Frontend

  • What is The useEffect Hook and How it Works?

  • How is Data Fetched With useEffect?

• Creating a Custom Hook

• Conclusion

How is React Initialized in Our Project?

If you look at your src folder, you should have the following files.

src
|- assets
|- App.css
|- App.jsx
|- index.css
|- main.jsx

Before we write any code, let’s remove the assets folder and the App.css file. We don’t need these two. Since we’re using Tailwind, the only place we need for CSS is the index.css file.

Now let’s take a look at main.jsx.

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.jsx'

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

For React to be used in a webpage, it needs to inject the content of your app within your HTML. To be more precise, we first need to create a root within your index.html file from which your React app will be rendered.

If you take a look at your index.html file at the root of your project’s folder. You will notice the presence of a div with an id of “root”. This was added automatically by Vite.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite + React</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

Looking back at our React code :

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

We can see that to inject our React app within the div having the id “root” we pass that div as a param of the createRoot function. It then creates an object that has a method called render . We immediately call it to pass our main React component called App wrapped under StrictMode (which adds useful behaviors to more easily find bugs).

What are React Components?

The component is the main building block when working in React. It allows you to build UIs in a modular fashion allowing you to reuse components in multiple places. It also allows you to manage complexity by placing logic specific to a component within it.

At a basic level, a React component is just a JavaScript function that returns some JSX. Which, if you remember, is syntax that looks like HTML that you can write within JavaScript in a .jsx file.

Here is an example!

function App(){ 
  return (
    <div>
      <h1>Hello World!</h1>
    </div>
  );
}

We have a React component that returns a div containing an h1 tag with the content “Hello World!”. You will surely notice that we defined this component by defining a function with its name’s first letter capitalized. The convention when defining React components is to use the PascalCase notation rather than the usual camelCase.

Another thing that makes components really useful in React is that you can place React components within React components, enabling a modular approach to building UIs. Here’s another example.

function Card() {
  return <section>This is a card</section>
}

function App() {
  return (
    <div>
      <h1>Results</h1>
      <div>
        <Card />
      </div>
    </div>
  )
}

As you can see, to place a component within another you can use the self closing tag notation you’re used to from HTML along with the name of that component.

React VS React-DOM

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'

Looking back at the import statements we had in main.jsx. You’ll notice that we’re importing things from both react and react-dom. You might be wondering why they are separate entities?

React is the library that allows us to build UIs using reusable blocks called components that return JSX. React-DOM on the other hand is the one taking care of rendering React components on the DOM (Document Object Model) of the webpage.

That’s why createRoot is imported from react-dom and not react since it’s used to render to the DOM with the render method. The reason for this split is that React can be used outside of the web. For example, it can be used for mobile development with React Native. Instead of the JSX being translated to HTML elements that are rendered on a webpage, they’re are translated to native mobile UI elements instead.

In addition to React being used for mobile UIs, it can also be used to make pdfs with react-pdf.

Making Our First React Component

Now that you understand how components work, let’s define our first component, the App component.

If you take a look at main.jsx again, you’ll notice that we’re already importing this component from a file called App.jsx.

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.jsx' // <--

createRoot(document.getElementById('root')).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

Let’s start from scratch by deleting everything in the existing App.jsx file and adding the following code which will display the app’s name and logo.

export default function App() {
  return (
    <main className="w-full p-2 flex flex-col items-center">
      <div className="flex items-center">
        <h1>Game Database</h1>
        <img src="./logo.png" className="w-25 h-25" />
      </div>
    </main>
  );
}

The main tag will contain all of the content of the search page. We define it as a flex container with a direction set to column. We then center the content within that main tag along the cross axis of the container using items-center. Below is a schematic displaying how the axis are defined according to the direction of the flex container. Remember that using items-center will center the content of the flex container along the cross axis while justify-center will center its content along the main axis.

We then make the main tag take the full available width of the page using w-full and give it a padding of 2 with p-2. All of the styling explained above is succinctly described in Tailwind by passing the needed class names to the className property of the JSX element.

<main className="w-full p-2 flex flex-col items-center">

Now, you might be wondering why is it className instead of class that you’re accustomed to in HTML? The reason is that there is a difference in how the attribute is named in HTML vs the DOM which the underlying model representing a webpage. Since React operates on the DOM it was chosen to use className instead class which is what the DOM uses.

Now within the main tag, we define a div which will hold the app’s name and logo.

<div className="flex items-center">
  <h1>Game Database</h1>
  <img src="./logo.png" className="w-25 h-25" />
</div>

This div is set as a flex container with the direction set to row by default, so we don’t need to specify it. We center its content along the cross axis so that the app’s title and logo are near each other at the center.

We then use an img tag to display the logo. You might have noticed that the path to the image does not contain the public folder despite the image being in that folder. That’s because Vite will automatically make whatever is in the public folder as if it was available from the root of the project, so you do not need to specify the public folder in the path.

Finally w-25 and h-25 sets the size of the logo using units defined by Tailwind which are responsive.

If you now start a development server using the command npm run dev in your terminal, you should get the following result.

Let’s makes things prettier before moving on. In index.html add the following Tailwind classes to the body tag.

 <body class="bg-gray-950 bg-[url('./background.png')] bg-repeat">

We’re setting the background color to be of gray-950 which is a color predefined by Tailwind that is near black. We then set the background image and set it to repeat so that it tiles indefinitely making the image cover the page regardless of the size of the viewport.

You should have the following result.

As you can see the app’s name near the logo is not visible. To fix the issue, let’s add a nice looking gradient to it. To showcase how you can create custom classes composed of Tailwind classes, let’s add the following in our index.css file.

.text-gradient {
  @apply bg-linear-to-r from-[#5c2bd9] via-[#fb6e6e] to-[#ffe137] bg-clip-text text-transparent;
}

The key here is to use the @apply directive and then use the Tailwind classes you need.

bg-linear-to-r from-[#5c2bd9] via-[#fb6e6e] to-[#ffe137]

Creates the gradient.

bg-clip-text text-transparent

Makes sure the gradient is applied within the text’s letters.

If you go back to our React component and apply the custom Tailwind class we created along with a few other Tailwind classes, you should get the following result.

  <h1 className="text-gradient text-4xl font-bold">Game Database</h1>

Creating The Search Component

In the previous section we created our main React component acting as the entrypoint of our UI. However, we need to define more than just one component in our app. To keep things organized, let’s create a components folder under the src folder. Within, let’s define our next component, the Search component by creating a Search.jsx file.

src
|- components
|    |- Search.jsx
|- App.jsx
|- main.jsx
|- index.css

Add the following code in Search.jsx.

export default function Search({ query, onChange }) {
  return (
    <div className="w-full mb-4">
      <div className="flex my-2 rounded-md shadow-xl bg-gray-800 p-4">
        <img
          className="relative top-0.5 h-5 w-5"
          src="./search.svg"
          alt="search"
        />
        <input
          className="w-full focus:outline-none ml-2 text-gray-300"
          type="text"
          placeholder="Search a game"
          value={query}
          onChange={onChange}
        />
      </div>
    </div>
  );
}

The Search component is essentially a search bar. You’ll probably notice that we have params that are passed to this component. These are called props. It’s another one of React’s major concepts.

What Are Props in React?

What makes components flexible in React is the ability to pass props to them to change how they’re rendered. This makes components usable in more than just one screen or one place in the app.

You can view props the same way as params that you pass to a function.

Here is a basic example of how props are used in React.

function Title(props) {
  return <h1>{props.name}</h1>;
}

function App() {
  return (
     <div>
       <Title name="Hello World" />
     </div>
  );
}

To pass props to a component you can simply start adding arbitrary attributes to where you call this component. In the example above, I decided to use an attribute called “name” that is then available under the props object where the component is defined. That’s why I can do props.name and get access to “Hello World”.

You might have noticed that we use curly braces when putting prop.name within the h1 tag. This is important, so that the actual value, “Hello World” is what’s rendered rather than having literally “prop.name” displayed.

A more convenient way of dealing with props is to use destructuring which is a JavaScript concept allowing us to directly get the properties we need.

function Title({name}) {
  return <h1>{name}</h1>
}

So now, if I need more than one prop, I can do the following.

function Title({name, subtitle}){
  return (
    <div>
      <h1>{name}</h1>
      <h2>{subtitle}</h2>  
    </div>
  );
}

function App() {
  return (
    <div>
      <Title name="Hello World" subtitle="Hello World Again!" />
    </div>
  );
}

Now that you understand what props are and how they work, let’s further analyze the code for the Search component.

export default function Search({ query, onChange }) {
  return (
    <div className="w-full mb-4">
      <div className="flex my-2 rounded-md shadow-xl bg-gray-800 p-4">
        <img
          className="relative top-0.5 h-5 w-5"
          src="./search.svg"
          alt="search"
        />
        <input
          className="w-full focus:outline-none ml-2 text-gray-300"
          type="text"
          placeholder="Search a game"
          value={query}
          onChange={onChange}
        />
      </div>
    </div>
  );
}

Most of the Tailwind classes here are easy to understand if you already know CSS so I will not go over each of them. I would like however, to explain a few that may not be as straightforward to figure out :

• mb-4 : Applies 4 units to the bottom margin of the element. If you had ml instead, it would be applied for margin left, mr for margin right, etc…

• my-2 : Applies 2 units to both the top and bottom margin of the element. Therefore, along the y axis. If you where to use mx, the left and right margins would be increased instead since they’re along the x axis.

Now let’s take a look at the input element.

export default function Search({ query, onChange }) {
  return (
    {/* previous code omitted for clarity */}
        <input
          className="w-full focus:outline-none ml-2 text-gray-300"
          type="text"
          placeholder="Search a game"
          value={query} <--
          onChange={onChange} <--
        />
    {/* next code omitted for clarity */}
  );
}

In React, the input attribute has two properties that are very useful.

1. The value attribute allowing us to set the value inside the field.

2. The onChange attribute which takes a function and will run it every time the user types in the field. Which also allows us the get what was typed.

We pass to these two attributes the query and onChange props we defined for the Search component. Now, go back to App.jsx and add the following code.

import { useState } from "react";
import Search from "./components/Search";

export default function App() {
  const [searchQuery, setSearchQuery] = useState("");

  return (
    <main className="w-full p-2 flex flex-col items-center">
      {/* previous code omitted for clarity */}
      <div className="w-full max-w-4xl">
        <Search
          query={searchQuery}
          onChange={(e) => setSearchQuery(e.target.value)}
        />
      </div>
    </main>
  );
}

What is this useState function we’re using? It’s called a hook and hooks are another one of React’s major concepts.

What Are Hooks in React?

Hooks let you use different React features from your components. You can either use the built-in hooks or combine them to build your own.

The useState Hook

 const [searchQuery, setSearchQuery] = useState("");

Here in particular, we’re using a state hook to set a state variable with the goal of holding the user’s search query and to update the UI when it changes.

From React’s docs, the usefulness of the useState hook is made apparent.

To update a component with new data, two things need to happen:

1. Retain the data between renders.

2. Trigger React to render the component with new data (re-rendering).

Creating a state variable using the useState hook allows us to achieve both.

1. A state variable to retain the data between renders.

2. A state setter function to update the variable and trigger React to render the component again.

In our case, searchQuery is the state variable and setSearchQuery is the state setter function. Finally, we pass within useState() the default state value we want to use.

When creating a state variable here is the convention that is usually adopted.

 const [nameOfTheVariable, setNameOfTheVariable] = useState(<default value. can be a number, null, a string, etc...>);

What makes React convenient for building UIs rather than using vanilla JS is that you don’t need to manual update the UI by changing the content of various HTML nodes. As we saw above, by using a state variable, React will take care of updating the UI automatically when the state variable changes.

<Search
  query={searchQuery}
  onChange={(e) => setSearchQuery(e.target.value)}
/>

By passing an onChange function that calls the state setter function setSearchQuery and passing to it the value of what was typed using e.target.value, we update the searchQuery state variable.

Since we’re also passing the searchQuery state variable to the Search component, React will re-render the component everytime it’s changed.

You should get the following result.

We could have defined the state variable within the Search component but it’s better to do it in the App component instead. This is a better approach because we need to have access to searchQuery so that we can pass it to our backend and make the RAWG API call to get relevant search results.

Setting Our Backend to Enable Search Requests to The RAWG API

Now that the search bar is completed, let’s do some backend work to be able to query the RAWG API so it can provide the data we need.

Setting Up Express

In your backend repo, add the following code to your index.js file.

import express from "express";
import cors from "cors";
import rateLimit from "express-rate-limit";
import fetch from "node-fetch";
import dotenv from "dotenv";

dotenv.config(); 

const API_KEY = process.env.API_KEY;
if (!API_KEY) {
  throw new Error("API key not found in environment variables");
}
const app = express();

const corsOptions = {
  origin: process.env.CLIENT_DOMAIN,
  allowedHeaders: ["Content-Type", "Authorization"],
};

app.use(cors(corsOptions));

const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // Limit each IP to 100 requests per windowMs
  message: "Too many requests from this IP, please try again later.",
});

// Apply rate limiting to all API requests
app.use(limiter);

We first import all the needed packages. I explained why we needed each of them in part 1 of this tutorial. Refer to it here.

We then call dotenv.config() to load our environment variables. We can then access them using process.env.<nameofthevariable>

We intialize the express web framework which is the core of our backend and pass it to a const called app.

We then set our CORS (stands for Cross Origin Resource Sharing) options which allows us to only authorized requests coming from the domain of our frontend. One thing to know about CORS is that it’s only enforced through the web browser. That means, a mobile app could still make requests to our backend despite the options we set. Learn more about CORS here.

Using app.use(cors(corsOptions)), we apply the CORS options to our Express app.

Finally we set up our rate limiter preventing potential DDoS attacks where a client makes too many requests in order to take down our backend.

To make our backend actually do something let’s add the following code.

app.get("/api/games", async (req, res) => {
    // TODO
});

const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

We define our first route that the client will be able to call and then make the Express app run by using app.listen.

Defining The /api/games Route

We want this route to return a list of games that matches the query passed by the client.

In Express, a route is defined this way.

app.get("/api/games", async (req, res) => {
    // TODO
});

Here we’re using a GET route since we’re not modifying a resource, we’re just requesting it. The first param is the route path we want to use, while the second param contains the function that’s going to run when the request is made. req.query will contain the query of the client. Clientside, the query will be passed as a param to the route path. Here’s an example.

/api/games?search=Zelda

Will result in req.query containing {search: “Zelda”}.

Now let’s continue by filling out the logic for the route.

app.get("/api/games", async (req, res) => {
  const { search: searchQuery } = req.query;
 
  try {
    const response = await fetch(
      `https://api.rawg.io/api/games?key=${API_KEY}&search=${searchQuery}`,
      {
        method: "GET",
        headers: {
          //Authorization: `Bearer ${API_KEY}`, some APIs requires using the authorization header but not this one
          "Content-Type": "application/json",
        },
      }
    );

    if (!response.ok) {
      return res
      .status(500)
      .json({ error: "Failed to fetch data from external API" });
    }

    const data = await response.json();
    return res.json(data);

  } catch (error) {
    console.error(error);
    return res
      .status(500)
      .json({ error: "Failed to fetch data from external API" });
  }
});

Let’s break it down.

const { search: searchQuery } = req.query;

By using object destructuring we rename the search param to searchQuery. We do this because the RAWG API expect a search param and it would look weird to do :

`https://api.rawg.io/api/games?key=${API_KEY}&search=${search}`

However, this is just a matter of personal preference. You can decide to stick with search if you want.

Within the Try/Catch statement we make the call to the RAWG API passing our API key from our environment variables.

const response = await fetch(
      `https://api.rawg.io/api/games?key=${API_KEY}&search=${searchQuery}`,
      {
        method: "GET",
        headers: {
          //Authorization: `Bearer ${API_KEY}`, some APIs requires using the authorization header but not this one
          "Content-Type": "application/json",
        },
      }
    );

Something to note is that the RAWG API expects you to pass the API key as a param rather than putting it in the Authorization header like other APIs. Also, in Node.js you can’t use fetch by default as you can on the frontend. That’s why we had to install the node-fetch package.

The rest of the code is pretty standard error handling. Either way, we always end up returning json with either an error message or the data the client requested.

Finally, remember to run the backend using the following command :

node index.js

Fetching Search Data on The Frontend

Now that we have created the backend route we needed, let’s head back to our frontend to write the logic allowing us to fetch the relevant data according to what query the user entered in the search bar.

We need to first talk about another very important hook in React called useEffect.

What is The useEffect Hook and How it Works?

To put it simply, it’s a hook that lets you synchronize a component with an external system. In our case it’s going to be our backend.

In practice, it’s a function that’s called within a component and takes usually two params. The first is the function you want to run which is your “effect” and the other is a dependency array. It will run after the component is first rendered and every time a dependency in its dependency array changes.

import { useEffect } from "react";

export default function myComponent() {

  useEffect(() => {
     console.log("will run only once in prod and twice in dev");
  }, []);

  return <h1>Test</h1>;
}

Above is an example of how we use useEffect. We have an empty dependency array meaning that the effect will run only after the component renders the first time. This occurs once in prod but twice in development because we wrapped our app with StrictMode.

You can use useEffect without a dependency array but it will run after every render.

useEffect(() => {
  console.log("This runs after every render");
});

How is Data Fetched With useEffect?

import { useState, useEffect } from "react";

function myComponent() {
  const [getNewQuote, setGetNewQuote] = useState(false);
  const [currentQuote, setCurrentQuote] = useState("");

  useEffect(() => {
    
    // prevent calling api after the component first renders
    if (!getNewQuote) return;

    // async function needed within because the function passed to useEffect cannot be async.
    const fetchData = async () => {
      const response = await fetch("https://example.com/api/quote");
      const data = await reponse.json()
      
      setCurrentQuote(data.text);
      setGetNewQuote(true);

    }
    fetchData();
  }, [getNewQuote]);

  return (
    <div>
      <h1>{currentQuote}</h1>
      <button onClick={() => setSearch(true)}>Display New Quote</button>
    </div>
  );

}

In the example above, we fetch and display a new quote from a fictitious API when the user clicks on a button. You’ll notice that the dependency array of our useEffect has the getNewQuote state variable. This means that the hook will run once after the component is rendered the first time (twice in dev because of StrictMode) and then every time getNewQuote is modified.

In practice, if you design your app in a way that you need the user to click a button to make an API call, you do not need to use useEffect as you could put the fetching logic within a function you pass to the button’s onClick handler. The example above was just to demonstrate at a basic level how this hook works.

In our app’s case, its usage is warranted since we need to make an API call when the user finishes typing something rather than clicking a button.

While using this hook like shown above is ok for toy examples, in practice when dealing with APIs, I would recommend using a library like Tanstack Query formerly known as React Query which makes fetching, caching, synchronizing and updating server state a breeze.

I recommend this part of the React docs regarding useEffect. Oftentimes, you might be tempted to use it while it’s not necessary. The docs provide helpful guidance regarding this hook.

In our app, we will still use useEffect but also create our own hook to deal with loading states (what to show the user while we’re fetching data) and error handling.

Creating a Custom Hook

While React offers hooks like useEffect and useState, nothing prevents you from creating your own hook. This is what we’re going to do now. Our hook is going to be called useFetch and will be responsible for fetching the data we need from our backend and dealing with loading states and errors if they occur.

Create a new folder called hooks within the src folder and within a file called useFetch.js.

src
|- components
|- hooks
    |- useFetch.js

In the file you just created, add the following code :

import { useState } from "react";

export default function useFetch(fetchFunction) {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const fetchData = async () => {
    try {
      setLoading(true);
      const result = await fetchFunction();
      setData(result);
    } catch (error) {
      setError(error);
    } finally {
      setLoading(false);
    }
  };

  const reset = () => {
    setData(null);
    setLoading(false);
    setError(null);
  };

  return { data, loading, error, fetchData, reset };
}

useFetch will expect a fetch function which will contain the API call and pass it to its own fetchData function and set the appropriate loading or error states depending ont the situation. The hook returns the data, the loading state, the error state, the fetchData function to fetch data again if needed and finally, a reset function to reset the state if needed.

Let’s create the fetch function specific to getting the list of games related to a search query. For this purpose, let’s create file called api.js within the src folder. In it, add the following code.

src
|- components
|- hooks
|- api.js

const API_ENDPOINT = import.meta.env.VITE_API_ENDPOINT;

export async function fetchGames({ query }) {
  const response = await fetch(`${API_ENDPOINT}/games?search=${query}`);
  return await response.json();
}

For the code above to work we need to define an environment variable in our frontend. This is done just to make it easy to swap in and out the domain of the backend as needed and not for security reasons.

Create at the root of your project a .env file containing the domain of our backend.

VITE_API_ENDPOINT="http://localhost:3000/api"

Now, we can go to App.jsx where we will write the logic to fetch the needed data when the user enters a query in the search bar.

import { useEffect, useState } from "react";
import useFetch from "./hooks/useFetch";
import { fetchGames } from "./api";

export default function App() {
  const [searchQuery, setSearchQuery] = useState("");

  const { data, loading, fetchData, error, reset } = useFetch(() =>
    fetchGames({ query: searchQuery })
  );

  useEffect(() => {
    const timeoutId = setTimeout(async () => {
      if (searchQuery.trim()) {
        await fetchData();
        return;
      }
    }, 500);

    return () => clearTimeout(timeoutId);
  }, [searchQuery]);

  return (
// ... rest of the code omitted for clarity

Let’s break it down.

const [searchQuery, setSearchQuery] = useState("");
const { data, loading, fetchData, error, reset } = useFetch(() =>
    fetchGames({ query: searchQuery })
);

We call useFetch and pass to it an anonymous function that will call our fetchGames function created in the api.js file and pass to it the user’s search query. The reason we’re wrapping it in a function is that we don’t want to call fetchGames immediately but rather let useFetch call it in its fetchData function. We also couldn’t pass it on its own because we wouldn’t be able to pass the search query param along.

Once called, the useFetch hook will return all that we need to display the relevant UI depending on the situation.

useEffect(() => {
    const timeoutId = setTimeout(async () => {
      if (searchQuery.trim()) {
        await fetchData();
      }
    }, 500);

    return () => clearTimeout(timeoutId);
}, [searchQuery]);

Next, we have our useEffect. We set a timeout of 500ms as to provide enough time after the user has typed before making a request otherwise we would be making a call every time a letter changes which would be wasteful. This is called debouncing.

Then, we have an if statement with a call to trim() that removes any whitespace at the beginning and end of a string. If the user didn’t type anything yet or just uses spaces in the search bar, an empty string will be returned which is falsy in JavaScript. Therefore, no API call will be made.

Since useEffect will run after the component first renders, in that case the search bar would be empty, we wouldn’t want to make an API call after all.

The function we pass to useEffect returns a function that clears the timeout we just created. This is called a cleanup function and is optional when using this hook but needed in our case. This is so we can avoid memory leaks. If we were to not use one here, every time the hook runs, we would create a new timer that would never be deleted.

That’s about it. The logic for fetching data is done. To make sure that it actually works, let’s console.log the data fetched. Below the useEffect we just added, create another one with the following content. (Yes, you can have more than one useEffect per component.)

export default function App() {

  useEffect(() => {
    // code omitted ...
  }, [searchQuery]);

  useEffect(() => {
    if (data) console.log(data)
  }, [data]);

  return (
  //... code omitted
}

Make sure to re-run both the frontend with npm run dev and the backend with node index.js. Now, if you try using the app. You should get the following result.

Conclusion

In the last part of this tutorial, we will write the logic to display the search results in nice looking game card components and then work on displaying more details when the user clicks on a specific card.

UPDATE : Part 3 is now available!