DEV Community: Gregory Mitchell

[Boost]

Gregory Mitchell — Wed, 21 May 2025 14:55:14 +0000

Gregory Mitchell

May 14 '25

Kotlin's Performance and What it Means

#kotlin #programming #coding #performance

Comments 3

6 min read

Kotlin's Performance and What it Means

Gregory Mitchell — Wed, 14 May 2025 15:02:17 +0000

Kotlin is a modern programming language that has gained popularity for its concise syntax and interoperability with Java. As I've been exploring Kotlin, it's come to become my favorite programming language. I built the benchmarks application in Kotlin, and included Kotlin as one of the languages it compares against. In this post, I want to share my thoughts on Kotlin's performance and how it compares to other languages.

Performance Overview

Kotlin JVM ranks last. And it's not close.

At first, I thought this was a fault on my part. Maybe I was measuring the wrong thing, or maybe I was using the wrong libraries. But after some investigation, I found that Kotlin's performance is consistently lower than the rest of the languages in the benchmarks. I even decided to turn on compiler optimizations for this language at one point, and it still didn't help.

Let's take a look at how the app actually works. It works by running the same program simultaneously 25 times and taking the average of the results. This means that if one of the programs is slow, it will affect the overall performance. However, it also includes the minimum time it took to run the program, which is a good indicator of how fast the program can be. This means that if one of the programs is slow, it will affect the overall performance.

Bubble Sort Example

Here's an example using the Bubble Sort benchmark that I created:

I immediately notice some very high spikes. This must mean that it's dragging down the average time, right?

Nope.

Kotlin Native performs at the benchmark I would expect it to run, but it's minimum time is still leagues behind the other languages. This means that even though it can run at a decent speed, it still has a lot of room for improvement. However, let's remind ourselves that this was measured in microseconds, with a fundamental difference of only just a millisecond or two. This is a very small difference, and it can be attributed to the fact that Kotlin is a newer language and is still being optimized. However, I would expect it to be at least on par with the other languages in the benchmarks.

Why is This?

Let's take a look at some decompiled Kotlin code. This is a decompiled example of the TabroomAPI library that I created.

/* Decompiler 33ms, total 130ms, lines 156 */
package dev.gmitch215.tabroom.api;

import kotlin.Metadata;
import kotlin.jvm.internal.Intrinsics;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

@Metadata(
   mv = {2, 1, 0},
   k = 1,
   xi = 48,
   d1 = {"\u0000\"\n\u0002\u0018\u0002\n\u0002\u0010\u0000\n\u0000\n\u0002\u0010\u000e\n\u0002\b\u0004\n\u0002\u0010\u000b\n\u0002\b\u0012\n\u0002\u0010\b\n\u0002\b\u0002\b\u0087\b\u0018\u00002\u00020\u0001B/\u0012\u0006\u0010\u0002\u001a\u00020\u0003\u0012\u0006\u0010\u0004\u001a\u00020\u0003\u0012\u0006\u0010\u0005\u001a\u00020\u0003\u0012\u0006\u0010\u0006\u001a\u00020\u0003\u0012\u0006\u0010\u0007\u001a\u00020\b¢\u0006\u0004\b\t\u0010\nJ\t\u0010\u0012\u001a\u00020\u0003HÆ\u0003J\t\u0010\u0013\u001a\u00020\u0003HÆ\u0003J\t\u0010\u0014\u001a\u00020\u0003HÆ\u0003J\t\u0010\u0015\u001a\u00020\u0003HÆ\u0003J\t\u0010\u0016\u001a\u00020\bHÆ\u0003J;\u0010\u0017\u001a\u00020\u00002\b\b\u0002\u0010\u0002\u001a\u00020\u00032\b\b\u0002\u0010\u0004\u001a\u00020\u00032\b\b\u0002\u0010\u0005\u001a\u00020\u00032\b\b\u0002\u0010\u0006\u001a\u00020\u00032\b\b\u0002\u0010\u0007\u001a\u00020\bHÆ\u0001J\u0013\u0010\u0018\u001a\u00020\b2\b\u0010\u0019\u001a\u0004\u0018\u00010\u0001HÖ\u0003J\t\u0010\u001a\u001a\u00020\u001bHÖ\u0001J\t\u0010\u001c\u001a\u00020\u0003HÖ\u0001R\u0011\u0010\u0002\u001a\u00020\u0003¢\u0006\b\n\u0000\u001a\u0004\b\u000b\u0010\fR\u0011\u0010\u0004\u001a\u00020\u0003¢\u0006\b\n\u0000\u001a\u0004\b\r\u0010\fR\u0011\u0010\u0005\u001a\u00020\u0003¢\u0006\b\n\u0000\u001a\u0004\b\u000e\u0010\fR\u0011\u0010\u0006\u001a\u00020\u0003¢\u0006\b\n\u0000\u001a\u0004\b\u000f\u0010\fR\u0011\u0010\u0007\u001a\u00020\b¢\u0006\b\n\u0000\u001a\u0004\b\u0010\u0010\u0011¨\u0006\u001d"},
   d2 = {"Ldev/gmitch215/tabroom/api/Judge;", "", "firstName", "", "lastName", "school", "location", "hasParadigm", "", "<init>", "(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Z)V", "getFirstName", "()Ljava/lang/String;", "getLastName", "getSchool", "getLocation", "getHasParadigm", "()Z", "component1", "component2", "component3", "component4", "component5", "copy", "equals", "other", "hashCode", "", "toString", "tabroom-api"}
)
public final class Judge {
   @NotNull
   private final String firstName;
   @NotNull
   private final String lastName;
   @NotNull
   private final String school;
   @NotNull
   private final String location;
   private final boolean hasParadigm;

   public Judge(@NotNull String firstName, @NotNull String lastName, @NotNull String school, @NotNull String location, boolean hasParadigm) {
      Intrinsics.checkNotNullParameter(firstName, "firstName");
      Intrinsics.checkNotNullParameter(lastName, "lastName");
      Intrinsics.checkNotNullParameter(school, "school");
      Intrinsics.checkNotNullParameter(location, "location");
      super();
      this.firstName = firstName;
      this.lastName = lastName;
      this.school = school;
      this.location = location;
      this.hasParadigm = hasParadigm;
   }

   @NotNull
   public final String getFirstName() {
      return this.firstName;
   }

   @NotNull
   public final String getLastName() {
      return this.lastName;
   }

   @NotNull
   public final String getSchool() {
      return this.school;
   }

   @NotNull
   public final String getLocation() {
      return this.location;
   }

   public final boolean getHasParadigm() {
      return this.hasParadigm;
   }

   @NotNull
   public final String component1() {
      return this.firstName;
   }

   @NotNull
   public final String component2() {
      return this.lastName;
   }

   @NotNull
   public final String component3() {
      return this.school;
   }

   @NotNull
   public final String component4() {
      return this.location;
   }

   public final boolean component5() {
      return this.hasParadigm;
   }

   @NotNull
   public final Judge copy(@NotNull String firstName, @NotNull String lastName, @NotNull String school, @NotNull String location, boolean hasParadigm) {
      Intrinsics.checkNotNullParameter(firstName, "firstName");
      Intrinsics.checkNotNullParameter(lastName, "lastName");
      Intrinsics.checkNotNullParameter(school, "school");
      Intrinsics.checkNotNullParameter(location, "location");
      return new Judge(firstName, lastName, school, location, hasParadigm);
   }

   // $FF: synthetic method
   public static Judge copy$default(Judge var0, String var1, String var2, String var3, String var4, boolean var5, int var6, Object var7) {
      if ((var6 & 1) != 0) {
         var1 = var0.firstName;
      }

      if ((var6 & 2) != 0) {
         var2 = var0.lastName;
      }

      if ((var6 & 4) != 0) {
         var3 = var0.school;
      }

      if ((var6 & 8) != 0) {
         var4 = var0.location;
      }

      if ((var6 & 16) != 0) {
         var5 = var0.hasParadigm;
      }

      return var0.copy(var1, var2, var3, var4, var5);
   }

   @NotNull
   public String toString() {
      return "Judge(firstName=" + this.firstName + ", lastName=" + this.lastName + ", school=" + this.school + ", location=" + this.location + ", hasParadigm=" + this.hasParadigm + ")";
   }

   public int hashCode() {
      int result = this.firstName.hashCode();
      result = result * 31 + this.lastName.hashCode();
      result = result * 31 + this.school.hashCode();
      result = result * 31 + this.location.hashCode();
      result = result * 31 + Boolean.hashCode(this.hasParadigm);
      return result;
   }

   public boolean equals(@Nullable Object other) {
      if (this == other) {
         return true;
      } else if (!(other instanceof Judge)) {
         return false;
      } else {
         Judge var2 = (Judge)other;
         if (!Intrinsics.areEqual(this.firstName, var2.firstName)) {
            return false;
         } else if (!Intrinsics.areEqual(this.lastName, var2.lastName)) {
            return false;
         } else if (!Intrinsics.areEqual(this.school, var2.school)) {
            return false;
         } else if (!Intrinsics.areEqual(this.location, var2.location)) {
            return false;
         } else {
            return this.hasParadigm == var2.hasParadigm;
         }
      }
   }
}

Already we can see some of the reason for the slow runtime.

Kotlin performs metadata comparison at runtime to make sure that the types and versions are correct. This is a very expensive operation, and it can slow down the performance of the program. You can see the metadata in the @Metadata annotation at the top of the class.
Instrinsics preserves null safety and type checking, as well as making sure that variables are equal in the auto-generated code.

These two features are great for making sure that the code is safe and correct, but they come at a cost. The performance of the program is affected by these features, and it can be very slow in some cases.

Conclusion

This was a short analysis about Kotlin's performance. I think that Kotlin is a great language, and I love using it. However, I think that it has a long way to go before it can be considered a high-performance language. The performance of the program is affected by the features that make it safe and correct, and I think that this is a trade-off that is worth making. However, I would like to see some improvements in the performance of the language in the future.

Making Combinatory: Map Search Algorithms

Gregory Mitchell — Mon, 28 Apr 2025 15:10:31 +0000

The Combinatory video game works as a mathematics game where you swipe tiles and combine them into eachother using mathematics operations, trying to get a specific score. This article will detail how I developed the Map Search Algorithm to create randomly generated levels.

Full Function

Here is the full function, according to the open-source paths.kt file in the calculatory repository:

/**
 * The directions a player can make on a grid. Represent up, down, left, and right.
 */
val directions = listOf(
    Pair(0, 1),
    Pair(0, -1),
    Pair(1, 0),
    Pair(-1, 0)
)

/**
 * Find all the possible values that can be obtained by moving on a grid.
 *
 * Worst-case time complexity is `O((4m)^k)`, where `m` is the size of [functions] and k is the number of tiles that can be visited from [sx] and [sy]. This significantly decreases, as the algorithm prunes duplicate results and utilizes
 * coroutines for parallel processing.
 *
 * For example, various testing on the [Mock Example](https://pl.kotl.in/t60amvt1e), which includes a 11x11 grid with 15 functions and 28 empty tiles, took `1.5s` and generated `73,118` values.
 * @param grid The grid to move on, represented as a 2D Double Array. Values of `0` represent an empty tile.
 * @param functions The operations to apply to the values.
 * @param sx The starting x coordinate.
 * @param sy The starting y coordinate.
 * @return A set of all the possible values that can be obtained by moving on the grid.
 * @see <a href="https://pl.kotl.in/t60amvt1e">Mock Example</a>
 */
suspend fun findValues(
    grid: Array<DoubleArray>,
    functions: List<Operation>,
    sx: Int,
    sy: Int
): Set<Double> = coroutineScope {
    val size = grid.size

    require(grid.isNotEmpty()) { "Grid must have at least one row" }
    require(grid[0].isNotEmpty()) { "Grid must have at least one column" }
    require(sx in grid.indices) { "Starting X Coordinate must be within the grid" }
    require(sy in grid[0].indices) { "Starting Y Coordinate must be within the grid" }
    require(grid.all { row -> row.size == size }) { "Grid must be square" }

    val channel = Channel<Double>()
    val visited = mutableSetOf<Pair<Int, Int>>()
    val values = mutableSetOf<Double>()

    suspend fun exploreValue(value: Double, cx: Int, cy: Int, operations: List<Operation>) {
        var hasMoved = false

        directions.forEach directions@{ (dx, dy) ->
            val nx = cx + dx
            val ny = cy + dy

            if (nx < 0.0 || nx >= size) return@directions
            if (ny < 0.0 || ny >= size) return@directions

            if (grid[nx][ny] == 0.0) return@directions
            if ((nx to ny) in visited) return@directions

            visited.add(nx to ny)
            val nv = grid[nx][ny]

            operations.forEach { o ->
                val newValue = o(value, nv)
                if (newValue in values) return@forEach

                values.add(newValue)
                channel.send(newValue)

                val remaining = operations.toMutableList()
                remaining.removeAt(remaining.indexOf(o))
                exploreValue(newValue, nx, ny, remaining)

                hasMoved = true
            }

            visited.remove(nx to ny)
        }

        if (!hasMoved || operations.isEmpty())
            channel.send(value)
    }

    val sv = grid[sx][sy]
    launch {
        exploreValue(sv, sx, sy, functions)
        channel.close()
    }

    for (value in channel)
        values.add(value)

    return@coroutineScope values
}

Analysis

At its barebones, Combinatory level data can be represented as a 2D Number Array:

[
    [ 0, 1, 2, 3, 4 ]
    [ 0, 4, 0, 2, 1 ]
    [ 0, 3, 2, 3, 2 ]
    [ 0, 1, 4, 6, 2 ]
    [ 2, 0, 3, 2, 0 ]
]

We can immediately notice that 0 in this instance represents tiles that are not declared. Therefore, this 5x5 grid example demonstrates that there are some holes in this map.

All Combinatory map data starts as an integer, but can shift to decimal values based on division operations present, which is why the map algorithm uses an Array<DoubleArray> as opposed to an Array<IntArray>. The function also intakes a List<Operation>, which are the operations that are present (addition, subtraction, multiplication, or division), and starting X (sx) and Y (sy) coordinates.

Requirements

The function starts off requiring a few things:

The Array rows or columns can't be empty
Starting coordinates must match valid coordinates in the Array
The Array must be square, or have idential width and height lengths

Implementation

First, the method uses an asynchronous channel to be able to handle multiple paths at once (more on that below), a visited set of pair coordinates to act as an asynchronous mutex to prevent two paths from moving at the sametime, and and the final values set that we will return. The difference between a List and a Set is that a Set is unordered and will reject duplicate values, meaning that we reduce performance overhead and unnecessary space when multiple paths with the same outcome are found. This also works with visited where we only have to know which places were visited.

As we continue to the actual method implementation, the method defines a local function exploreValue which makes a step in any random direction given the current value. This method is called recursively until the player runs out of directions to go to. This reflects the implementation details of the actual game, where you swipe in any direction for any kind of operation until you run out of operations to swipe with. This is demonstrated through looping through both the directions and the operations array, where the former is looped through at random into new asynchronous anlayzers and the latter has its elements removed until it runs out.

After the steps have completed, the channel is closed, and the values are collected into a Set.

Results & Asynchronousity

The function integrates with Kotlin's Suspend functions to reduce time complexity values and explore multiple paths at the same time. It sends the values to a Channel<Double> which then propogates those into a proper Set<Double>, or all of the possible values for every single combination in a map.

Use Cases

While this method is specific to Combinatory, this algorithm is a performative example for how map search can be implemented in Kotlin within a 2D Array. You can utilize this method in your own applications to analyze result data of different maps present in your program.

Conclusion

This was a short but informative explanation about the Map Search Algorithm in the Combinatory Video Game. Stay tuned for more in-depth analysis.

Making Combinatory: Introduction to KorGE

Gregory Mitchell — Mon, 28 Apr 2025 15:09:24 +0000

This will be a short series on how I made the Combinatory video game using the KorGE game engine. I will be going over the basics of the game engine, how I set up the project, and how I implemented the game itself. I will also be going over some of the challenges I faced and how I overcame them.

I have mixed feelings about KorGE. On one hand, it's great, and has a lot of potential. On the other hand, one person maintains the entire thing, which make bugs like
trying to make a working iOS Build take near half a year to even get a response. I mean,
soywiz is a great guy, but he's only one person. I'm sure he's looking for help, but I'm not sure if I'm ready to take on that kind of responsibility, at least when I
have another dozen side projects to work on.

Entry Point

The entry point of the game looks like this:

suspend fun main() = Korge(
    gameId = ID,
    title = TITLE,
    windowSize = SIZE,
    backgroundColor = MAIN_COLOR,
    icon = ICON
) {
    container = sceneContainer(defaultTransition = TRANSITION)
    container.addTo(this)
    loadingSequence(this)

    // UI
    registerScenes()
    title()

    if (Os.CURRENT.isDesktop)
        devMode()
}

ID is set to xyz.calcugames.combinatory, or the package name of the game.
TITLE is set to Combinatory, or the name of the game.
SIZE is set to Size(390, 844), which mimicks the size of a mobile phone.
- The web version automatically fills in the remaining space with MAIN_COLOR.
MAIN_COLOR is set to 0x17558c, or a dark blue.
ICON is the path to the icon of the game stored in the resources folder.

The next TRANSITION is the transitioning scene between the loading screen and the main menu, as well as other scene containers in the game. It's just a default
fade transition.

KorGE makes things really nice when it comes to setting up the game. Just open up a container and boom, you're in the game. No need to worry about setting up
OpenGL or anything like that. It's all done for you.

Loading Sequence

The loading scene looks like this:

class LoadingScene : Scene() {

    override suspend fun SContainer.sceneMain() {
        val text = text("Loading...", 64.0) {
            centerXOnStage()
            y = 100.0
        }

        while (!loaded) {
            text.tween(text::y[height - 100], time = 3.0.seconds, easing = Easing.EASE_IN_OUT)
            text.tween(text::y[100.0], time = 3.0.seconds, easing = Easing.EASE_IN_OUT)
        }
    }

}

KorGE uses Scenes to manage different windows that need to be shown. My loading screen is just a "Loading..." text going up and down until the game is loaded.
This could take anywhere from under a second to near a minute, depending on how fast your computer or phone is. I figured this would satisfy the user's need to
be entertained while the game is loading in a simple game.

KorGE's animation suite is great. It feels like I'm using CSS animations, but in a game engine. I can tween any property of any object, and it will animate
smoothly. I can even tween multiple properties at once, and it will still animate smoothly. It's really nice. The design for using extension functions on
properties is highly clever as well. I can just type text::x or text::color and boom, I'm animating the x position or color of the text. It's amazing.

Level Scene

Finally, I'll show some of the loading operations for the level scene. It's pretty complicated, has a lot of variables, and is arguably highly important. I'm also
not going to reveal anything.

In short, calculatory, or the open source portion with all the algorithms, converts level data into the
LevelZ File Format, which is a level format I created for general use. The game then reads the level data and creates the level
from that.

The auto-generated levels, like the Daily Level and the Endless modes, use multiple seeded values (that are internal so you can't predict them) to generate the
level data. The game then reads the level data and creates the level from that.

Calculatory has an algorithm for getting all of the possible path values in each area:

suspend fun findValues(
    grid: Array<DoubleArray>,
    functions: List<Operation>,
    sx: Int,
    sy: Int
): Set<Double> = coroutineScope {
    val size = grid.size

    require(grid.isNotEmpty()) { "Grid must have at least one row" }
    require(grid[0].isNotEmpty()) { "Grid must have at least one column" }
    require(sx in grid.indices) { "Starting X Coordinate must be within the grid" }
    require(sy in grid[0].indices) { "Starting Y Coordinate must be within the grid" }
    require(grid.all { row -> row.size == size }) { "Grid must be square" }

    val channel = Channel<Double>()
    val visited = mutableSetOf<Pair<Int, Int>>()
    val values = mutableSetOf<Double>()

    suspend fun exploreValue(value: Double, cx: Int, cy: Int, operations: List<Operation>) {
        var hasMoved = false

        directions.forEach directions@{ (dx, dy) ->
            val nx = cx + dx
            val ny = cy + dy

            if (nx < 0.0 || nx >= size) return@directions
            if (ny < 0.0 || ny >= size) return@directions

            if (grid[nx][ny] == 0.0) return@directions
            if ((nx to ny) in visited) return@directions

            visited.add(nx to ny)
            val nv = grid[nx][ny]

            operations.forEach { o ->
                val newValue = o(value, nv)
                if (newValue in values) return@forEach

                values.add(newValue)
                channel.send(newValue)

                val remaining = operations.toMutableList()
                remaining.removeAt(remaining.indexOf(o))
                exploreValue(newValue, nx, ny, remaining)

                hasMoved = true
            }

            visited.remove(nx to ny)
        }

        if (!hasMoved || operations.isEmpty())
            channel.send(value)
    }

    val sv = grid[sx][sy]
    launch {
        exploreValue(sv, sx, sy, functions)
        channel.close()
    }

    for (value in channel)
        values.add(value)

    return@coroutineScope values
}

Pretty cool stuff. I'll show some more later. This was just a short look into the inner workings on the game, which I definetly need to promote more. I'll be
working on that soon. Stay tuned for the next part of the series.

cmdfx v0.1.3 - Physics Engine in the Terminal

Gregory Mitchell — Sat, 19 Apr 2025 02:34:09 +0000

Been through a few revisions since v0.1.0 of the cmdfx Game Engine. This is a short video showcasing the features in v0.1.3 of the engine,
which included some new features in the Physics Engine.

The source code in question is the launcher sample available here:

/**
 * @file launcher.c
 * @author Gregory Mitchell (me@gmitch215.xyz)
 * @date 2025-03-28
 * 
 * This is a simple demo program that shows how to use the Physics Engine for CmdFX.
 * 
 * Simply run the program and watch the object fly around the screen.
 * You can optionally pass a multiplicative modifier to the tick speed as the first parameter
 * to see how fast it will go.
 * 
 * @copyright Copyright (c) 2025
 * 
 */

#include <cmdfx.h>
#include <stdio.h>
#include <stdlib.h>

int main(int argc, char** argv) {
    char** data = Char2DBuilder_createFilled(5, 5, '%');
    data[0][0] = 0;
    data[4][0] = 0;
    data[0][4] = 0;
    data[4][4] = 0;

    CmdFX_Sprite* sprite = Sprite_create(data, 0, 0);

    double speed = 1;
    if (argc > 1) {
        speed = atof(argv[1]);
        if (speed > 0) CmdFX_setTickSpeed((int) (CmdFX_getTickSpeed() * speed));
    }

    if (argc > 2) {
        double friction = atof(argv[2]);
        if (friction >= 0) Engine_setDefaultFrictionCoefficient(atof(argv[2]));
    }

    Canvas_clearScreen();
    Canvas_hideCursor();
    Engine_enableMotionDebug();
    CmdFX_initThreadSafe();

    Canvas_hLine(0, Engine_getGroundY(), Canvas_getWidth(), '-');
    Canvas_hLine(0, 1, Canvas_getWidth(), '-');
    Sprite_draw(2, Canvas_getHeight() - sprite->height - 1, sprite);
    Engine_start();

    CmdFX_Vector* velocity = Vector_create(2, 2);
    Sprite_addForceFor(sprite, velocity, 300 / speed);
    sleepMillis(10000 / speed);

    Engine_end();
    free(velocity);
    Sprite_free(sprite);
    CmdFX_destroyThreadSafe();

    Canvas_showCursor();

    return 0;
}

Breakdown

First, we create a 5x5 sprite with a border of % characters. This is done using the Char2DBuilder_createFilled function, which creates a 2D array of characters filled with the specified character. The 0 at the end removes the corners of the sprite, making it look like a rounded square. The sprite is then created using the Sprite_create function, and we leave the Z-index and ANSI codes at 0 for no unnecessary data.

Next, there are some extra parameters for the program. The first parameter is a speed modifier, which is multiplied by the current tick speed. The tick speed in this case is how fast the Physics Engine processes new information. The tick speed by default is 12, so you can set it to 0.5 to get a slower effect, or 2 for a much faster engine. This allows you to see how fast the object will go if you want to test it out. The second parameter is the default friction coefficient. In Physics, this is used in the calculation for the deceleration of the object when it is moving (or the friction of the object). The default value is 0.5, but you can set it to 0 to see how fast the object will go without any friction. This is useful for testing out the engine and seeing how fast it can go.

Then, we move on to some canvas commands:

Canvas_clearScreen() clears the screen so we get a clean slate to work with.
Canvas_hideCursor() hides the cursor so it doesn't show up on the screen.
Engine_enableMotionDebug() enables the motion debug mode, which shows the motion of each individual sprite drawn on the screen. This is the information tab shown in the top left of the screen shown in the video.
CmdFX_initThreadSafe() initializes the thread-safe mode for the engine. This is used to make sure that the engine is thread-safe and can be used in a multi-threaded environment, which is necessary for the engine to work properly. This method is also automatically called by Engine_start() if you don't want to call it manually.

Now, we draw some visuals on the screen:

Canvas_hLine(0, Engine_getGroundY(), Canvas_getWidth(), '-') draws a horizontal line at the bottom of the screen, which is the ground level for the engine. The Engine_getGroundY() function gets the Y position of the ground level, and Canvas_getWidth() gets the width of the screen.
Canvas_hLine(0, 1, Canvas_getWidth(), '-') draws a horizontal line at the top of the screen, which is the top of the screen.

These are just for visual purposes and doesn't do anything else other than visualize the top and bottom of the screen.

After we draw the sprite with Sprite_draw(2, Canvas_getHeight() - sprite->height - 1, sprite), we start the engine with Engine_start(). This starts the engine and begins processing the physics for the sprite.

The CmdFX_Vector* velocity = Vector_create(2, 2) creates a new vector with the specified X and Y values. This is used to set the velocity of the sprite. The Sprite_addForceFor(sprite, velocity, 300 / speed) adds a force to the sprite for the specified amount of time. The 300 / speed is the amount of time in milliseconds that the force will be applied to the sprite. This is used to make the sprite move in a certain direction. Like in Physics, forces increase the acceleration of the object, and this is how we can make the object move in a certain direction. The sleepMillis(10000 / speed) is used to pause the program for the specified amount of time. This is used to give the sprite time to move before the program ends. The 10000 / speed is the amount of time in milliseconds that the program will pause for. This is used to give the sprite time to move before the program ends.

Finally, we end the engine with Engine_end(), free the memory for the vector and sprite, and destroy the thread-safe mode with CmdFX_destroyThreadSafe(). This is done to clean up any resources that were used by the engine and free up memory. Then, we show the cursor again with Canvas_showCursor() to make sure that the cursor is visible again.

Conclusion

This is a simple demo program that shows how to use the Physics Engine for CmdFX. It is a simple program that shows how to use the engine and how to create a sprite with a border. The program is simple and easy to use, and it is a good starting point for anyone who wants to learn how to use the engine. The engine is still in development, and there are many more features to come in the future. I hope you enjoy using the engine and have fun with it!

Writing Unit Tests in C

Gregory Mitchell — Fri, 11 Apr 2025 13:15:01 +0000

Introduction

We all love C, right? You can basically write anything that you want. But that comes at the cost of you trying to debug everything. So, I'll explain my process of writing unit tests in C, utilizing the CTest Framework with CMake.

The code used in this example is borrowed from the cmdfx library.

Prerequisites

Let's assume your file tree looks something like this:

|CMakeLists.txt
|README.md
|LICENSE
|test/
├── CMakeLists.txt
├── src/
│   ├── test1.c
│   ├── test2.c
│   ├── test3_main.c
│   ├── test3_others.c
│   └── test.h
|include/
└── library.h

In your root CMakeLists.txt, get started with this code:

option(TESTING "Build tests for ${PROJECT_NAME}" ON)
if (TESTING)
    enable_testing()
    add_subdirectory(test)
endif()

This will allow you to start configuring tests when you run cmake .. in the test directory.

Now, in your test/CMakeLists.txt, you can add the following code:

cmake_minimum_required(VERSION 3.16)

include(CTest)

# Tests
function(add_test_executable name)
    set(TEST_NAME "test-${name}")

    # Create the test executable
    add_executable("${TEST_NAME}" "src/${name}.c" "src/test.h")
    target_include_directories("${TEST_NAME}" PRIVATE "${PROJECT_SOURCE_DIR}/include")

    # Link the library to the test executable
    add_dependencies("${TEST_NAME}" "${PROJECT_NAME}")

    # Set the test executable name
    string(REPLACE "_" "/" TEST_EXECUTABLE_NAME ${name}) # Replace underscores with slashes in name
    add_test(NAME ${TEST_EXECUTABLE_NAME} COMMAND "${TEST_NAME}") # Add test command

    # Set the test executable properties if needed
    if (CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
        # Add coverage flags for GCC/Clang
        target_compile_options("${TEST_NAME}" PRIVATE --coverage -lm -w) # Link with math library and suppress warnings
        target_link_options("${TEST_NAME}" PRIVATE --coverage)
    endif()

    # Set the output directory for the test executable
    set_target_properties(${TEST_NAME} PROPERTIES
        RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin/tests/
    )
endfunction()

# Find Test Files
file(GLOB TESTS "src/*.c")

foreach(TEST_FILE ${TESTS})
    get_filename_component(TEST_NAME ${TEST_FILE} NAME_WE)

    # Call the preceding function to add the test executable
    add_test_executable(${TEST_NAME})
endforeach()

This code will create a function that you can call to add test executables. You can also add the --coverage flag to your tests if you want to.

Writing Tests

`test.h`

test.h is a header file that contains assertion functions that can be used to check the results of your tests. It also contains a function to run all tests.

Here's a modified example of test.h that includes the assertion functions. Now, I usually use a as my actual value instead of my expected value, so feel free to modify this to fit what you usually like to code with:

#ifndef PROJECT_TEST_H
#define PROJECT_TEST_H

// Define the test result strings
#define PASS "PASS"
#define FAIL "FAIL"

#include <stdio.h>
#include <string.h>
#include <math.h>

// Initialize the test counter
static int count = 1;

int assertTrue(int condition) {
    printf("#%d: %s\n", count, condition ? PASS : FAIL);
    if (!condition) {
        printf("#%d: had true, wanted false\n", count);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertFalse(int condition) {
    printf("#%d: %s\n", count, !condition ? PASS : FAIL);
    if (condition) {
        printf("#%d: had false, wanted true\n", count);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertNull(void* ptr) {
    printf("#%d: %s\n", count, ptr == 0 ? PASS : FAIL);
    if (ptr != 0) {
        printf("#%d: why is <%p> not null\n", count, ptr);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertNotNull(void* ptr) {
    printf("#%d: %s\n", count, ptr != 0 ? PASS : FAIL);
    if (ptr == 0) {
        printf("#%d: this pointer shouldn't be null bro\n", count);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertEquals(int a, int b) {
    printf("#%d: %s\n", count, a == b ? PASS : FAIL);
    if (a != b) {
        printf("#%d: had <%d>, wanted <%d>\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertFloatEquals(float a, float b) {
    // use fabs for float comparison because of precision issues
    printf("#%d: %s\n", count, fabs(a - b) < 0.0001f ? PASS : FAIL);
    if (fabs(a - b) >= 0.0001f) {
        printf("#%d: had <%f>, wanted <%f>\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertDoubleEquals(double a, double b) {
    // use fabs for double comparison because of precision issues
    printf("#%d: %s\n", count, fabs(a - b) < 0.0001 ? PASS : FAIL);
    if (fabs(a - b) >= 0.0001) {
        printf("#%d: had <%f>, wanted <%f>\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertNotEquals(int a, int b) {
    printf("#%d: %s\n", count, a != b ? PASS : FAIL);
    if (a == b) {
        printf("#%d: had <%d>, didn't want <%d>\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertGreaterThan(int a, int b) {
    printf("#%d: %s\n", count, a > b ? PASS : FAIL);
    if (a <= b) {
        printf("#%d: wanted <%d> to be greater than <%d>\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertLessThan(int a, int b) {
    printf("#%d: %s\n", count, a < b ? PASS : FAIL);
    if (a >= b) {
        printf("#%d: wanted <%d> to be less than <%d>\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertIn(double value, double min, double max) {
    printf("#%d: %s\n", count, value >= min && value <= max ? PASS : FAIL);
    if (value < min || value > max) {
        printf("#%d: expected <%f> to be in range <%f> to <%f>\n", count, value, min, max);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertPointersMatch(void* a, void* b) {
    printf("#%d: %s\n", count, a == b ? PASS : FAIL);
    if (a != b) {
        printf("#%d: expected pointers <%p> and <%p> to match\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertStringsMatch(char* a, char* b) {
    if (a == 0 || b == 0) {
        printf("#%d: %s\n", count, a == b ? PASS : FAIL);
        if (a != b) {
            printf("#%d: expected strings <%s> and <%s> to match\n", count, a, b);
            count++;
            return 1;
        }
    }

    printf("#%d: %s\n", count, strcmp(a, b) == 0 ? PASS : FAIL);
    if (strcmp(a, b) != 0) {
        printf("#%d: expected strings <%s> and <%s> to match\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

#endif

Other Test Files

For this example, I'm going to modify an example from the CmdFX testing suite. Now, you can create your test files.

#include <stdio.h>

#include "cmdfx/core/sprites.h"
#include "test.h"

int main() {
    int r = 0;

    CmdFX_Sprite* sprite = Sprite_createFilled(5, 5, '&', 0, 0);
    Sprite_draw(4, 4, sprite);

    r |= assertEquals(sprite->x, 4);
    r |= assertEquals(sprite->y, 4);

    Sprite_moveTo(sprite, 2, 2);

    r |= assertEquals(sprite->x, 2);
    r |= assertEquals(sprite->y, 2);

    Sprite_moveBy(sprite, 1, 1);

    r |= assertEquals(sprite->x, 3);
    r |= assertEquals(sprite->y, 3);

    return r;
}

This test file creates a sprite and moves it around. It uses the assertion functions to check if the sprite's position is correct after each move.
You can create as many test files as you want, and they will all be compiled into separate executables. You can also use the assert functions in any of your test files.

Running Tests

To run the tests, you can use the following command:

ctest --output-on-failure

This will run all the tests and show the output for any failed tests. You can also use the --coverage flag to generate a coverage report.

Conclusion

Writing unit tests in C can be a bit tricky, but with the right tools and techniques, it can be done easily. The CTest framework with CMake makes it easy to create and run tests, and the assertion functions in test.h make it easy to check the results of your tests. I hope this guide helps you get started with writing unit tests in C!

Reverse-Engineering Cookies with Ktor and Ksoup

Gregory Mitchell — Sun, 06 Apr 2025 19:20:30 +0000

Introduction

Tabroom is a website used by the Speech & Debate community to check tournament data, read ballots, look at judges, and basically serves as the primary hub of managing competitions. It was created by Chris Palmer as a hobby project and is now property of the National Speech & Debate Association.

As I've continued development on a TabroomAPI, which scrapes the HTML content of the website to provide readable data, I eventually found myself having to introduce an authentication suite for accessing new content on the website. Now, Tabroom has this neat little website called api.tabroom.com that has a lot of the same data as the main website, but in a much more usable format.

The only problem was that entire API... isn't actually accessible to the public, nor is it widely documented outside of its OpenAPI specification. Most of its methods are for specifically marked accounts. This means that I was presented with a dilemma: Either drop the authentication suite, or somehow reverse-engineer the Set-Cookie header when logging in through the HTML page to retrieve a session ID.

And I'm no quitter, so here's how I did it.

Prerequisites

TabroomAPI is built on top of Ktor, a Kotlin-based HTTP client and server framework. This means that I needed to use Ktor's HttpClient to make the requests to the Tabroom API. If you don't have Ktor set up, you can follow the Ktor documentation to get started.

On top of this, because it scrapes HTML content, I also needed to use the Jsoup and Ksoup libraries to parse the HTML content and extract the necessary values. Because it's built on top of Ktor, it's available on multiple plaforms, meaning I needed to find different libraries to parse the HTML content on different platforms, and use different Ktor engines. For example, on Android, it uses the OkHttp engine, while on iOS, it uses the Darwin engine, and on the JVM, it uses the Java engine introduced in JDK11. You can look at the full build.gradle.kts file to see the dependencies and how they are set up.

As a result, it uses its own Document and Element classes as wrappers built on top of these libraries.

// Minimalistic document library only for the things I need
internal class Document(
    val url: String,
    val html: String
) {

    val body: Element
        get() = querySelector("body") ?: throw IllegalStateException("Document does not have a body element")

    val bodyElements: String
        get() = body.innerHTML
            .replace(Regex("<script\\b[^>]*>([\\s\\S]*?)</script>"), "")
            .replace(Regex("<style\\b[^>]*>([\\s\\S]*?)</style>"), "")

    val head: Element
        get() = querySelector("head") ?: throw IllegalStateException("Document does not have a head element")

}

// Performs a CSS Query Selection on the document
internal expect fun Document.querySelectorAll(selector: String): List<Element>
internal fun Document.querySelector(selector: String): Element? = querySelectorAll(selector).firstOrNull()
internal fun Document.getElementById(id: String): Element? = querySelector("#$id")
internal fun Document.getElementsByClassName(className: String): List<Element> = querySelectorAll(".$className")
internal fun Document.inputValue(name: String): String? {
    val input = querySelector("input[name=$name]") ?: return null
    return input["value"] ?: input["checked"]
}

// Minimilastic element library only for the things I needs
internal class Element(
    val tagName: String,
    val innerHTML: String,
    val textContent: String,
    val attributes: Map<String, String>,
    val children: List<Element>
) {
    operator fun get(attribute: String): String? = attributes[attribute]
}

Here's an example implementaton on the JVM:

import org.jsoup.Jsoup

private fun org.jsoup.nodes.Element.convert(): Element {
    return Element(
        tagName = tagName(),
        innerHTML = html(),
        textContent = text(),
        attributes = attributes().asList().associate { it.key to it.value },
        children = children().map { it.convert() }
    )
}

internal actual fun Document.querySelectorAll(selector: String): List<Element> {
    val doc = Jsoup.parse(html)
    return doc.select(selector).map { it.convert() }
}

Now that we have all of that settled, let's get started.

Inspecting the HTTP Request

The first thing I needed to figure out what how it naturally did it. It's pretty simple: Tabroom will send your username and password in plain text to the server, along with a SHA and Salt with the password. There were other parameters that were completely unrelated, but I didn't need them. The important part was that the server would respond with a Set-Cookie header, which is what I needed to get the session ID.

Looking through the Firefox network tab, this was pretty clear:

The TabroomToken value is a URL-encoded session ID, that is sent along with each header in a Cookie request to the website to signify that a user is logged in.

Retrieving the Token

This is what the HTML form looks like on Tabroom:

<form name="login" action="/user/login/login_save.mhtml" method="post" class="signin">
    <input type="hidden" name="salt" value="aBhZ7Ec3">

    <input type="hidden" name="sha" value="$6$aBhZ7Ec3$zymKdLO6lp4eBarEM2bvauJyuIAxHgUNKDF3mZFzlBA0HmA2WuTwAu2Y89akiPPSROLvU.RNC/uPRALVi6Ug4/">

    <div class="full centeralign flexrow martop">
        <span class="ninetenths marno padvertno padleft padright">
            <input type="text" id="username" name="username" class="noresize full" value="" autocomplete="on" placeholder="Email address">
        </span>
    </div>

    <div class="full centeralign flexrow">
        <span class="ninetenths marno padvertno padleft padright">
            <input id="password" name="password" class="noresize full" type="password" value="" placeholder="Password">
        </span>
    </div>

    <div class="full centeralign flexrow">
        <span class="ninetenths marno padvertno padleft padright">
            <input type="submit" value="Login" class="noresize full">
        </span>
    </div>
</form>

Before you say I "leaked anything" - the salt and sha values don't actually have any real security value. They are unique to every browser tab and change when you refresh the page every time. Because Tabroom is open source, you can see that these values are completely random and are used to generate the Session ID. Of course to actually create the session ID, you need the login credentials, which I obviously can't share. But, if you have a Tabroom account, you can easily get this information by inspecting the network tab in your browser.

In response, I created two Kotlin methods: One to get these randomly generated values, and the other to use my Tabroom Credentials to retrieve a Session ID.

// Use an engine from different platforms
internal expect val engine: HttpClientEngine

// Initialize our client
internal val client
    get() = HttpClient(engine) {
        expectSuccess = false
        followRedirects = false
    }

// Internal method to retrieve a document by its URL
internal suspend fun String.fetchDocument(useToken: Boolean = true): Document {
    val res = client.get(this) {
        headers {
            append("User-Agent", "Ktor HTTP Client, Tabroom API v1")

            append("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8")
            append("Accept-Language", "en-US,en;q=0.9")
            append("Connection", "keep-alive")
            append("Upgrade-Insecure-Requests", "1")
        }

        if (isLoggedIn && useToken)
            cookie("TabroomToken", token!!) // Use the "Cookie" function to set the cookie
    }

    if (!res.status.isSuccess()) throw IOException("Failed to fetch document: ${res.status}\n${res.bodyAsText(Charsets.UTF_8)}") // Print out the error message

    val text = res.bodyAsText(Charsets.UTF_8)
    return Document(this, text)
}

// Platform-specific url encoding/decoding
expect fun encodeURL(url: String): String
expect fun decodeURL(url: String): String


/**
 * Whether the API has currently stored a Session ID.
 */
val isLoggedIn: Boolean
    get() = token != null

/**
 * The current Session ID for the API.
 */
var token: String? = null
    private set

private suspend fun getSaltAndSha(): Pair<String, String> {
    val document = "https://www.tabroom.com/user/login/login.mhtml".fetchDocument() // Read and Parse HTML
    val salt = document.inputValue("salt") ?: throw IllegalStateException("Salt not found in document")
    val sha = document.inputValue("sha") ?: throw IllegalStateException("SHA not found in document")

    return Pair(salt, sha)
}

/**
 * Logs in to Tabroom with the given username and password.
 *
 * This function performs a login request to Tabroom and stores the authentication token in the `token` variable.
 * Tokens represent the Session ID and are valid for 1,024 hours, or roughly 42 days.
 * 
 * @param username The username to log in with.
 * @param password The password to log in with.
 * @return True if the login was successful, false otherwise.
 * @throws IOException If the login request fails.
 */
@JsName("loginAsync")
@JvmName("loginAsync")
suspend fun login(username: String, password: String): Boolean {
    val (salt, sha) = getSaltAndSha()

    val res = client.submitForm(
        "https://www.tabroom.com/user/login/login_save.mhtml",
        parameters {
            append("tourn_id", "")
            append("key", "")
            append("salt", salt)
            append("sha", sha)
            append("category_id", "")
            append("return", "")
            append("username", username)
            append("password", password)
        }
    ) {
        headers {
            append("User-Agent", "Ktor HTTP Client, Tabroom API v1")
            append("Content-Type", "application/x-www-form-urlencoded")
            append("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8")
        }
    }

    // Redirect value of 302 means sucess; Don't be fooled by a 200 or something else
    if (res.status.value != 302) throw IOException("Unexpected status code: ${res.status}")

    val cookie = res.setCookie() // Retrieve the value of 'Set-Cookie'
    if (cookie.isEmpty()) return false

    val tabToken = cookie.firstOrNull { it.name == "TabroomToken" }?.value // Get the value of 'TabroomToken'
    if (tabToken == null) return false
    if (tabToken.isEmpty()) throw IllegalStateException("TabroomToken is empty")

    token = decodeURL(tabToken) // Set the token variable to the decoded value
    return true
}

This is a pretty long chunk of code, but the comments should be self-explanatory. We first fetch the HTML document from the login page, and then parse the salt and sha values from the HTML. We then use these values to create a POST request to the login page with our username and password. If the request is successful, we retrieve the Set-Cookie header and extract the TabroomToken value, which is our session ID.

The login function returns a boolean value indicating whether the login was successful or not. If the login was successful, the token variable is set to the session ID, which can be used for subsequent requests to the Tabroom API.

Conclusion

Now that I have a proper login function, I can use it to authenticate with the Tabroom API and retrieve data from the website. This is a pretty simple example of how to reverse-engineer a cookie using Ktor, but it can be applied to other websites as well.

Some example applications are in the ginormous fetcher.kt file available on GitHub. I hope this article was useful to you on how we could reverse-engineer cookies using Ktor.

Using WakaTime to Boost Productivity

Gregory Mitchell — Sun, 06 Apr 2025 17:44:22 +0000

Note: I am not associated with WakaTime, nor did I get paid anything to write this. I just think it's a great tool that I wanted to share with you. Here's my WakaTime profile for reference. I have over 2,500 hours logged in programming as of writing this article since I installed the application in February 2022.

What is WakaTime?

WakaTime is a productivity tool that tracks the time you spend coding in various programming languages and IDEs. It provides detailed statistics on your coding habits, including the amount of time spent on different projects, languages, and even specific files. This data can help you identify patterns in your work and make informed decisions about how to improve your productivity.

I really enjoy it because I like to see how I've progressed as a programmer over the years. I spent a lot of time in Java around the time I discovered the tool, which is why I have over 1,200 hours in that language alone. That statistic is not only a good thing to put on my CV, but also as a general tracker to see how much I actually spend coding. I also like to see how much time I spend on different projects, which is a great way to see how much time I spend on my own projects versus schoolwork.

How to Use WakaTime

WakaTime comes as a plugin in various IDEs and text editors, including Visual Studio Code, IntelliJ IDEA, and Sublime Text. It's also a browser plugin, which is why my "Other" language is around 300 hours, since it tracks how much time I spend reading and reviewing GitHub issues and pull requests. You can install the plugin for your preferred IDE or text editor, and it will automatically start tracking your coding activity.

Is it a Keylogger?

No. All of WakaTime is open source, by the way, if you really think it's that deep. Their FAQ also details all of the safety measures you can take if you're afraid your file paths or project names will get out.

Deleting your account also wipes your data across all their servers. And, most of this "sensitive data" isn't actually public. What is public makes the application even better, in my opinion, which is why I like it much better than other code tracking statistics.

The Competitive Aspect

WakaTime also features a leaderboard system based on general coding time for that week, and the coding time in that week for a speicfic programming language. This in of itself is very interesting, as in introduces an anonymous yet competitive aspect to progamming, encouraging me to work more when I don't want to. It's pretty nice.

Other Nice Things

You could compare WakaTime to the other thousands of code stat tracking tools out there, but there's a few reasons why I like WakaTime over the others.

For one, it's open source, and the data is stored on your own servers. You can also self-host it if you want to, which is a nice feature. The other tools I've seen are either not open source or don't have the same level of detail in their statistics. Second, they have a really good way of visualizing all of your data. The graphs and charts look really sleek and are easy to read. My third and favorite thing that they do is that they can send all of this to your email so you don't have to remember to open up the app all the time. They have a nice, clean way of detailling a daily, weekly, monthly, even yearly reports about your leaderboard status and your hours coded.

These all make WakaTime a great tool for tracking your coding activity and improving your productivity. The data is easy to read and understand, and the competitive aspect adds an extra layer of motivation to keep coding.

Other Not so Nice Things

No good application is perfect. The bad ones pretend they are, and WakaTime doesn't. For one, their language detection system has always been pretty interesting. You can kind of control what language it is in your user settings, which means that there is probably always a fight between what a *.m or *.scs file is. I overrode the latter while I was developing StarCosmetics, and when I looked at the leaderboard, around 10,000+ people were now developing structures for my project. I don't know if that's a good thing or a bad thing, but it was interesting to see that I was the only one who had that language set to StarCosmetics. I think it would be nice if they had a way to override the language detection system for specific files, but I don't know how they would do that.

Another thing is that their plans are a little skewed. Free is free, and it is what it is. Basic doesn't really give you much of anything, and Premium gives you everything. I think Basic is a little overproced and Premium is a little underpriced.

I also joined in a weird time when they started making things available in the free plan now only available in the premium/basic plans. My old email reports were grandfathered in, but I technically can't modify them in any way because they are only available in the Basic plan. Because of how old the platform looks, it's probably built with an older tech stack, meaning that there have been bugs here or there.

Speaking of bugs, my biggest gripe is the fact that their web plugins are a little... terribly designed. For example, I use Cloudinary for one project, but haven't been able to figure out how to link the two together. In addition, when you use the github.dev vs a GitHub Codespace area, it appends [GitHub] to your project name, which is annoying.

Conclusion

Even with my few gripes, WakaTime is a great tool for tracking your coding activity and improving your productivity. It's easy to use, provides detailed statistics, and has a competitive aspect that can help motivate you to code more. If you're looking for a way to boost your productivity and track your coding habits, I highly recommend giving WakaTime a try. You can find more information on their website.

How to Name a Project

Gregory Mitchell — Mon, 31 Mar 2025 02:41:17 +0000

How do you properly name a programming project?

This is one of the most pressing issues for developers in 2025. This is arguably more important than AI replacing everything or your favorite language dying.

No: Mythological Figures

One of my golden rules is that your name needs to make sense. Naming a communication network "Hermes" may seem appealing, but it could mean a number of things. Usually you want your project to be visible in your search engine, because you want your project to be what developers need.

Why?

Because that's the goal of open source: You want your developers to use your project because it's good. Good projects have good names that make them stand out. That's fundamentally why you should avoid mythological figures: they make your project feel unoriginal.

Yes: Word Combinations

Using word combinations may seem weird. "BattleCards," "StarCosmetics," and "Novaconomy" were all terrible names I thought of during my Minecrafting phase. But they stood out on their own. Now, they're (somewhat) successful plugins with a combined ~5,000 downloads on Spigot, and ~10,000 across all platforms.

Usually weird is memorable, which is good. You want developers to remember your project. Sure, they can always star it for later, but not everyone does that. Developers see hundreds of git repositories every day, and the ones that remember yours are going to use it.

Think about all the times you've came across a GitHub project that fit exactly what you needed, but you couldn't remember how to find it, so you found a different one. Sometimes search history is your friend, and sometimes it can reveal to your friends that you really hate Go.

No: Brand-Exact

This one is probably the most controversial, even in an enterprise space. You shouldn't name your open-projects after your business brand.

This is liekly due to the psychology of how developers view the companies that maintain them: sure, they could be sponsoring every contributor to the project, but they don't. In addition, the most hardcore open source contributors are mostly anti-capitalist and pro-freeware, which may go against your employer's values. I'm not criticizing or revealing any political views here, I'm just stating the facts. Developers like open-source projects that feel like open source projects, and your project should reflect that initiative.

If you want me to be more specific, don't name your project after your company's mascot or logo word for word. More on that below.

Yes: Brand-Inspired

This is different than the above. You want your name to stand on its own, but if you're working for a company, you still need to put food on the table, so it should be associated with the company, not representative of the company.

If this is confusing, I'll give you an example. I'm working on a game under my company, Calculus Games, named Combinatory (click to play). The actual game is going to be closed-source (because of env vars), but I want to open-source as much as possible. The open source portion is named "calculatory" instead of "combinatory-public" simply because it's a brand that stands on its own independent of the "combinatory" brand name. The game, which will eventually be a for-profit inspired game, will not overshadow the open-source portion.

Conclusion

These are some short guidelines on naming your project. Listen to them, or don't. No one really cares. A name should reflect the developer's own personal choice, not what some random kid says on his website. Name your project however you want to, and do whatever you think works best for you.