Matthew Herman

Printing Diagnostics in Neovim

Sun, 18 Jun 2023 21:44:00 -0500

I’m starting to understand what is so great about the extensibility of (Neo)Vim.

The language server support built into Neovim will display diagnostic messages (errors, warnings, etc.) as a hovering tooltip to the right of the line where they occur. This is normally perfectly fine, but if you have a long line or message it will result in the message being cut off.

I wasn’t able to figure out how to view the message when that happens. It doesn’t seem to let you scroll to the right. There is probably some way to see them or to force them to be displayed elsewhere (for example, below the line), but I decided to use it as an opportunity to work with the Neovim API again.

We can retrieve the diagnostics for the current buffer using vim.diagnostic.get(0) and display them to the user with vim.notify(...). First we’ll handle the case where there are no diagnostics:

local diagnostics = vim.diagnostic.get(0)
if (not diagnostics or #diagnostics == 0) then
    vim.notify("No issues found", vim.log.levels.INFO)
    return
end

The log level passed to vim.notify affects how Neovim displays the message.

If there are diagnostics, we want to display them. I’m not sure how the order of the diagnostics table is determined, but we probably want to show them in line number order:

local function by_line_num (a, b)
    return a.lnum < b.lnum
end
...
table.sort(diagnostics, by_line_num)

Finally we build up a table of formatted messages, concatenate them, and display them as an error with vim.notify:

local messages = { "" }
local sev_text = {
    [vim.diagnostic.severity.ERROR] = "Error",
    [vim.diagnostic.severity.WARN] = "Warning"
}
for _, d in ipairs(diagnostics) do
    local sev = sev_text[d.severity] or "Info"
    table.insert(messages, sev..": "..d.message.." ["..d.lnum..":"..d.col.."]")
end
vim.notify(table.concat(messages, "\n"), vim.log.levels.ERROR)

The full function looks like this:

local function print_diagnostics()
    local function by_line_num (a, b)
        return a.lnum < b.lnum
    end

    local diagnostics = vim.diagnostic.get(0)
    if (not diagnostics or #diagnostics == 0) then
        vim.notify("No issues found", vim.log.levels.INFO)
        return
    end

    table.sort(diagnostics, by_line_num)
    local messages = { "" }
    local sev_text = {
        [vim.diagnostic.severity.ERROR] = "Error",
        [vim.diagnostic.severity.WARN] = "Warning"
    }
    for _, d in ipairs(diagnostics) do
        local sev = sev_text[d.severity] or "Info"
        table.insert(messages, sev..": "..d.message.." ["..d.lnum..":"..d.col.."]")
    end
    vim.notify(table.concat(messages, "\n"), vim.log.levels.ERROR)
end

Using that function we can view all diagnostic messages for a buffer at the same time.

It is incredibly powerful to be able to interact with your editor programatically. I think there is some risk that it becomes an infinite number of yaks to shave, but so far I’ve enjoyed using the Neovim API for tasks like this.

Trying to Write

Wed, 14 Jun 2023 14:40:00 -0500

I want to write.

A couple days ago I posted something for the first time since 2020. It felt good. I’ve always enjoyed writing (editing not so much), but I haven’t really had much opportunity since I finished college. I mean, I write every day at my job: emails, documentation, design docs, but those things aren’t really for me.

I haven’t written because of all the usual excuses. I don’t have time. I have nothing to write about. I’m not good enough at it. At the end of the day that’s all they are. Excuses.

I’ve mainly written about programming since it’s what I know and is something I enjoy. I’m hoping to continue to do so, but I also want to write about other things in my life like my family, my dogs, gardening, and nature.

If I post something at least once a month I think I will be happy with my progress. Like anything else, the more I do it the easier it will get.

Creating a Persistent Terminal in Neovim

Mon, 12 Jun 2023 19:40:00 -0500

I’ve dabbled with using Vim as an editor off and on over the years and it still hasn’t quite stuck. Mostly I have just switched to using Vim keybindings in other editors (such as VS Code and JetBrains Rider) since I like how ergonomic and quick they are.

A while back I became familiar with Neovim and was intrigued by the Lua API it exposes for configuration and plugins. Vimscript always seemed…strange, so it was refreshing to see it use a more popular, general-purpose programming language like Lua. I am once again attempting to learn to use (Neo)Vim and this time I tried my hand at some scripting in Lua.

While learning Lua (by doing the excellent exercises over at Exercism) I would often want to switch between my editor and another shell to run unit tests or test something in the REPL. I could do that using something like tmux or just separate tabs in my terminal emulator, but I wanted to be able to run the commands without leaving Neovim.

It turns out that Neovim provides the :terminal command which will start your default shell in a new buffer. I quickly created a keymap to run the command, but was disappointed by the workflow. To close the terminal I was running exit to exit my shell and then hitting enter to automatically close the buffer.

This quickly became annoying so I checked the docs and saw that I could return to normal mode with <C-\><C-n> and then hit <C-o> to return to my previous buffer. This worked fine (although desperately needed its own keymap), but whenever I would return to my terminal it would create a brand new shell and buffer instead of reusing the old one.

The terminal is a buffer like any other and will show up if you run :ls, but switching between buffers in that way is still slow for me so I wanted to try scripting my solution:

function toggle_terminal()
    for i, buffer in ipairs(vim.api.nvim_list_bufs()) do
        local buffer_name = vim.api.nvim_buf_get_name(buffer)
        if (string.sub(buffer_name, 1, 7) == "term://") then
            vim.api.nvim_win_set_buf(0, buffer)
            return
        end
    end
    vim.api.nvim_command(":terminal")
end

The function grabs the list of all buffers and looks for the first name that starts with term:// (the default naming scheme for terminal buffers) and sets the current window to that buffer if it finds one. Otherwise, it runs the :terminal command to open a new one. I tried to figure out how to use the nvim_term_open function instead of the command, but I couldn’t get it to work.

This worked great! The first time I run it Neovim will spin up a new terminal, but after that it will simply switch back to the original terminal with all of my output and history.

So far I’ve been enjoying Neovim, especially with all of the really nice plugins people have created for it. I have found telescope and nvim-tree to be really useful. The fact that LSP support is built-in rather than provided by plugins is also nice. The API documentation, which is available online and with the :help command, is very detailed, but the thing I’ve been missing the most has been examples of how to do certain tasks like creating a terminal with nvim_term_open. I could dig through the source of other plugins to figure it out, but most are complex enough that finding the specific use case I need is difficult. Overall, it feels like (Neo)Vim is “sticking” a little bit more for me now and may actually become an editor that I use regularly.

Functional Gift Wrapping

Sun, 13 Dec 2020 17:22:00 -0600

This year I decided to contribute to the F# Advent Calendar, a yearly event where members of the F# community share their thoughts with others through a series of blog posts and articles.

In light of the holiday season I chose a project that is related to something many of us our doing this time of year - wrapping gifts! But let me stop you before you get carried away with visions of present-wrapping robots or machine learning algorithms for selecting the best gifts. It’s not going to be quite that exciting, but it could help you be a more efficient wrapper.

I’m going to be walking through the implementation of one of my favorite algorithms: the Gift Wrapping algorithm. It’s an algorithm that is used to compute the “convex hull” of a set of points, which is the smallest subset of points which form a convex polygon that encapsulates all the remaining points.

The Gift Wrapping algorithm (also known as Jarvis march) is an interesting solution to the problem as it operates by wrapping the points similar to how you would wrap a gift. It has a time complexity of O(nh) where n is the total number of points and h is the number of points in the hull, so its performance is dependent on the size of the result set. It’s often outperformed by other convex hull algorithms, but it is simple to implement and interesting nonetheless. You can learn about some of the other algorithms here.

The Algorithm

We will be be working off of the pseudocode that is presented on the wikipedia page:

algorithm jarvis(S) is
    // S is the set of points
    // P will be the set of points which form the convex hull. Final set size is i.
    pointOnHull = leftmost point in S // which is guaranteed to be part of the CH(S)
    i := 0
    repeat
        P[i] := pointOnHull
        endpoint := S[0]      // initial endpoint for a candidate edge on the hull
        for j from 0 to |S| do
            // endpoint == pointOnHull is a rare case and can happen only when j == 1 and a better endpoint has not yet been set for the loop
            if (endpoint == pointOnHull) or (S[j] is on left of line from P[i] to endpoint) then
                endpoint := S[j]   // found greater left turn, update endpoint
        i := i + 1
        pointOnHull = endpoint
    until endpoint = P[0]      // wrapped around to first hull point

The algorithm is best explained visually. We start with a point that we know will be on the hull, the leftmost point in the set, which is point A in this case.

We then choose an arbitrary point in the set as our first endpoint. Let’s say we chose B. From here, we’re going to imagine a line through A and B by which we’re going to judge other points.

For each other point in the set we need to determine whether it is left of the line or right of the line. If it is left of the line, it becomes the new endpoint by which we test the remaining points. By the time we test every point, we’ll have identified the leftmost point (rotationally, relative to the last hull point) which must be on the hull as well.

So for example, we have A which is our pointOnHull, B which is our current endpoint, and we’re going to begin testing points. We might start with C. The point falls to the right of the line through A and B so we know C cannot be on the hull.

If we tested D next, we’d see that D is in fact to the left of the line. Since it’s further left than B, it becomes our new endpoint.

We would continue on to test E and F, both of which would be right of the line through A and D, and determine that D is the next point on the hull.

This process repeats with D as our new pointOnHull, then the next one we find, and so on until we make our way back to the original starting point. By then we’ll have finished identifying our convex hull.

An Imperative Approach

Before we implement the algorithm in F# functionally, I’d like to begin by showing it in the imperative style mirroring the pseudocode above. This will let us get to a working implementation quickly and give us a good starting point for an iterative refactor.

The only custom type we need for this is a simple Point record:

type Point = {
    X: int;
    Y: int;
}

The imperative implementation of our function toConvexHull: Point list -> Point list is the following:

let toConvexHull (points: Point list): Point list = 
    // Start at the leftmost point since it is guaranteed to be on the hull
    let startingPoint = points |> List.minBy (fun p -> p.X)

    let mutable hull = []
    let mutable pointOnHull = startingPoint

    let mutable atStartingPoint = false
    while not atStartingPoint do
        hull <- pointOnHull::hull
        let mutable endpoint = points |> List.head
        for candidatePoint in points do
            if (endpoint = pointOnHull) || (candidatePoint |> isLeftOfLine (pointOnHull, endpoint)) then
                endpoint <- candidatePoint
        pointOnHull <- endpoint
        atStartingPoint <- startingPoint = endpoint
    hull

You should be able to line it up with the pseudocode pretty easily. We get our startingPoint by finding the point in our list with the smallest X coordinate and then initialize our list of hull points and our first pointOnHull. From there we enter our while loop where we add our current pointOnHull to the hull and choose an arbitrary endpoint (the first item in the list) to test with. We then test each point in the set, and if it is further left than our endpoint, we make it the new endpoint. Once we’re done, we set pointOnHull to endpoint since it is our newest hull point. Then as long as that point wasn’t the one we started with, we start all over to find the next hull point.

The one bit that we’ve skimmed over on purpose is the isLeftOfLine function. That is the predicate we use to determine if candidatePoint is left of the line created by pointOnHull and endpoint. In order to explain its implementation, we’ll need to take a detour into some math…

One way we can determine whether a point is to the left (or right) of a line is by using a cross product. Cross products are used for all sorts of things that I don’t remember from school, but the one that is useful for us is the fact that the sign of the cross product determines whether the angle created by two vectors is clockwise or counter-clockwise. For example, imagine we have two vectors V1 and V2.

The cross product, V1 X V2, will be positive since the angle from V1 to V2 is counter-clockwise. The opposite cross product, V2 X V1, is negative because the angle is clockwise. I don’t know why this is true, just that it is.

So now if we have a line from A to B and a third point P, we can use the cross product to determine if the angle between A->B and A->P is counter-clockwise, which would mean that P is left of the line.

To do that we treat B and P as the two vectors, but since they’re starting from A rather than the origin (0,0) we need to subtract the vector A from each of them.

The formula to calculate the cross product of B and P is:

B X P = (Bx * Py) - (By * Px)

Which becomes the following after we subtract the vector A from both B and P:

(B - A) X (P - A) = ((Bx - Ax) * (Py - Ay)) - ((By - Ay) * (Px - Ax))

We can translate this into code as the function directionFromLine which is then used by isLeftOfLine.

type Direction =
    | Left
    | Right
    | Colinear

let directionFromLine a b p =
    let crossProduct =
        (b.X - a.X) * (p.Y - a.Y) - (b.Y - a.Y) * (p.X - a.X)
    if crossProduct > 0 then Left
    elif crossProduct < 0 then Right
    else Colinear

let isLeftOfLine (line: Point * Point) point =
    let (lineStart, lineEnd) = line
    match (directionFromLine lineStart lineEnd point) with
    | Left -> true
    | _ -> false

With that we’ve got a complete implementation of the Gift Wrapping algorithm, but it’s littered with loops and mutable state. Next we’ll work towards refactoring that code to be more functional in nature.

Towards a Functional Solution

Let’s approach this by trying to convert a piece at a time. The meat of the function is in the two loops: an inner for loop that is used to identify the next hull point and a surrounding while loop that collects them all.

We should be able to extract that inner for loop pretty easily. It takes a point it knows is on the hull, a point that could be on the hull, and then tests each of the other points, replacing the assumed new hull point whenever it finds one that is further left. This could be rewritten as a single reduce.

let findNextPointOnHull pointOnHull candidatePoints =
    candidatePoints
    |> List.reduce (fun endpoint candidatePoint ->
        if (endpoint = pointOnHull) || (candidatePoint |> isLeftOfLine (pointOnHull, endpoint)) then
            candidatePoint
        else
            endpoint)

The function passed to List.reduce takes an accumulator and the next element in the list. It starts by passing the first two elements of the list in, then the result of that with the third element, the result of that with the fourth element, and so on. We utilize this behavior by passing the potential hull point, endpoint as the accumulated value. In the function we test whether the next point in the list, candidatePoint is left of endpoint, and if so pass that point as the accumulated value instead. This lets us mimic the behavior of the for loop without the need for mutable state.

let toConvexHull (points: Point list): Point list = 
    let findNextPointOnHull pointOnHull candidatePoints =
        candidatePoints
        |> List.reduce (fun endpoint candidatePoint ->
            if (endpoint = pointOnHull) || (candidatePoint |> isLeftOfLine (pointOnHull, endpoint)) then
                candidatePoint
            else
                endpoint)

    let startingPoint = points |> List.minBy (fun p -> p.X)

    let mutable hull = []
    let mutable pointOnHull = startingPoint

    let mutable atStartingPoint = false
    while not atStartingPoint do
        hull <- pointOnHull:: hull
        pointOnHull <- findNextPointOnHull pointOnHull points
        atStartingPoint <- startingPoint = pointOnHull
    hull

Our code is looking a little more functional, but there’s still some work to do. A few mutable values remain and it would be great if we could eliminate that while loop.

Functional Gift Wrapping

The easiest way for us to replace that while loop is through recursion. This part of the algorithm is a natural fit since we are using a known hull point to find the next hull point, then using that new hull point to find the next hull point, and on and on, until we eventually hit our stop condition by running into our initial starting point. From there we just need to collect all of the values we’ve identified.

let rec findPointsOnHull startingPoint pointOnHull candidatePoints =
    let nextPointOnHull = findNextPointOnHull pointOnHull points
    if nextPointOnHull = startingPoint then
        [nextPointOnHull]
    else
        nextPointOnHull::(findPointsOnHull startingPoint nextPointOnHull candidatePoints)

With that recursive helper function defined, our final toConvexHull function looks like the following:

let toConvexHull (points: Point list): Point list = 
    let findNextPointOnHull pointOnHull candidatePoints =
        candidatePoints
        |> List.reduce (fun endpoint candidatePoint ->
            if (endpoint = pointOnHull) || (candidatePoint |> isLeftOfLine (pointOnHull, endpoint)) then
                candidatePoint
            else
                endpoint)

    let rec findPointsOnHull startingPoint pointOnHull candidatePoints =
        let nextPointOnHull = findNextPointOnHull pointOnHull points
        if nextPointOnHull = startingPoint then
            [nextPointOnHull]
        else
            nextPointOnHull::(findPointsOnHull startingPoint nextPointOnHull candidatePoints)

    let startingPoint = points |> List.minBy (fun p -> p.X)
    let pointOnHull = startingPoint
    findPointsOnHull startingPoint pointOnHull points

Conclusion

We now have a working, functional implementation of the Gift Wrapping algorithm.

If you would like to play with the application or view the complete source code, you can find the repository here. I implemented the small Fable application you see above. It will let you randomize the points and generate the convex hull. The three implementations of the algorithm can be found in src/GiftWrapping.fs.

Happy holidays!

.NET Core Tools

Sun, 30 Aug 2020 16:13:00 -0500

Beginning with .NET Core 2.1, developers are able to easily create and distribute “.NET Core Tools”. These tools are simply .NET console applications that are delivered as a special form of NuGet package. Due to how simple they are to create it is a great way to share small applications and tools with your fellow developers.

Creating .NET Core Tools

Creating a new .NET Core tool is as simple as creating a new console app, adding a few lines to the project file, and packaging the project. To begin, create your console application using dotnet new console. Update the generated project to do whatever you like (or just leave the default “Hello World!” implementation) and then add the following to the PropertyGroup node in your project’s .csproj:

<PackAsTool>true</PackAsTool>
<ToolCommandName>hello-world</ToolCommandName>

The PackAsTool element is what signifies that this should be packaged as a tool rather than a regular NuGet package. The ToolCommandName lets you optionally specify the command that should be used to run the tool. If it is not provided, it will default to the project name. As these tools are still NuGet packages you will also want to provide the usual NuGet metadata like an ID, version, etc. It’s important that you choose an ID that avoids any naming collisions if you’re publishing this to the public nuget.org repository.

The final steps are to build your project with dotnet build and then package it using dotnet pack. From there, all you need to do is upload it to a NuGet repository in order to make it available for others to install.

Using .NET Core Tools

Once the tool is packaged and published, users are able to install it using dotnet tool install -g <tool_name>. The -g switch will install the package globally. This adds the command to the machine’s path and allows it to be run anywhere by simply executing the appropriate command, like hello-world.

Starting in .NET Core 3.1, the SDK also supports installing tools locally to a project. This allows you to install different versions of the same tool in different workspaces. Local tools rely on a manifest file which can be used to restore/install all the tools necessary for that project. Local tools must be run via dotnet tool run <command_name>.

Before installing any tools make sure you trust the author and have reviewed the source if possible. These tools are not sandboxed or restricted in any way so it is vital that you know what you are installing. To uninstall a tool you can use the dotnet tool uninstall <tool_name> command. If the tool was installed globally, be sure to include the -g switch.

Additional Reading

Seven Day Roguelike 2020

Sun, 15 Mar 2020 16:49:00 -0500

This year I decided to join the Seven Day Roguelike (7DRL) game jam. It’s a week long event where participants spend time creating new roguelike games, individually or as a team. Games in this genre vary greatly but generally have the following elements:

Permadeath - players are unable to respawn after death, they must start the game from scratch
Procedural content - levels, enemies, and items are unique within each play of the game
Turn based - gameplay is turn based, encouraging tactics over reflexes
Simple graphics - usually ASCII or tile based

Some popular traditional roguelike games are NetHack, Angband, ADOM, and (of course) Rogue. Some newer games include DCSS, Brogue, and Cogmind.

I had never participated in a game jam and had very little experience with game development. This challenge gave me the opportunity to learn more about game development, roguelikes, and even a fun new algorithm. While I made less progress than I anticipated, it was an enriching experience and has introduced me to a new potential hobby.

Getting Started With Godot

When I tried to get into game development in the past I had used Phaser, but scarcely accomplished more than the tutorials. Since I was hoping to use this jam as another introduction to game development, I decided to choose a more fully featured game engine that would give me the ability to make all sorts of games once I invested the time into learning it.

Godot is a free and open source game engine that allows you to create both 2d and 3d games. Although not as polished, it at least seems similar to the big players like Unity and Unreal Engine. It was also appealing to me that it was open source since I try to use free software as much as possible for my personal projects. There are a range of roguelike-specific game libraries (rot.js, libtcod) that are often recommended for the game jam, but again, I wanted to learn something a little more general purpose than that.

I was pleased to find a really nice set of tutorials were available on their website. These range from informational articles on specific topics to a step-by-step tutorial where you make a full game from scratch. I found that while they didn’t use anything similar to a roguelike to demonstrate these concepts, they covered a wide enough range of material that I was much more prepared by the time I had finished them.

Game development with Godot is centered around creating “scenes” that are made up of trees of nodes that have different properties. These scenes can define specific entities like the player or enemies, as well as something more abstract like a map or level in the game. Generally these are then composed into a game via “instancing”. For example, if you were to define a Player scene you might start with a node called Area2D at the root which is used for 2d collision and physics. Then you would add children like a Sprite node for the characters image and a CollisionShape2D to define how it collides with other objects.

Player (Area2D)
  |---Sprite
  |---CollisionShape2D

An instance of this scene could then be added to a separate top-level scene that defines the game itself, which may have other nodes like the map and the heads-up display.

Main (Node)
  |---Player
  |---Map
  |---HUD

You can also instance scenes programatically. You would use that strategy for things that may be defined dynamically like enemies that spawn at different intervals.

Godot allows you to attach scripts to any node in a scene. These scripts basically define a class that extends whatever the type of the node is. They come with a variety of methods you can override related to the game loop such as _init, _ready, and _process. The documentation suggests you write your scripts using a language called GDScript which was created for the engine itself, but you can also use C# or C++. I decided to use GDScript because of its tight integration with the tooling even though I am more experienced with C#.

Communication between different nodes is done using an event system that Godot calls “signals”. There are predefined signals that nodes emit such as Area2D’s area_entered and area_exited but developers can also define their own signals to emit and handle.

With these basic building blocks we should be able to construct our entire game.

Entering the Labyrinth of the Lich

After spending a day going through Godot tutorials, it was time to get started on the game. I had given a little thought to what I wanted to create and had landed on a vague premise involving a spaceship taken over by alien lifeforms where the player would need to navigate their way to the escape pods in order to survive. This idea hit a roadblock when I failed to find any free sets of sci-fi sprites I could use for the game art. I’m definitely not an artist and I did not want to be slowed down even further by choosing to make my own art. Since most roguelikes are set in a fantasy world, there was a lot of art I could use if I chose that setting.

The new game (which I would later title “Labyrinth of the Lich”) would center around a wizard who must find his way through a series of mazes while encountering various enemies in a search for forbidden knowledge. The plan was to have a few levels of procedurally generated mazes with different types of enemies. This would culminate in a boss fight of some sort once the exit of last level ws reached. The player character would be limited in how many spells they could “know” at a time. Their starting spells would either be chosen at the beginning of the game or be randomly selected and then they could find additional spells to replace these within the game. These spells would be mix of offensive, defensive, and utility spells such as a fire AoE spell, a warding spell that splinters to damage attacking enemies, and invisibility.

I knew my plans were ambitious for someone with no experience but they gave me a set of concepts to focus on. Much of what I would end up spending my time on would be the general gameplay mechanics of roguelikes rather than the specifics of my game.

Time to Jam

The first thing I had to tackle was the creation of the map and the tiles that it is made up of. Eventually, I would want to procedurally generate these levels, but while trying to nail down the basic mechanics I just created a static set of rooms. I used Quale’s Scroll O’ Sprites for all of the game’s art. Since it is provided as a regular image file I had to use GIMP to crop out the sprites I needed in order to make a tileset. Then, within Godot I was able to create a Tilemap node that uses that tileset. A Tilemap is a node that allows you to define a set of tiles and easily “paint” them onto the screen in order to build the map. It also lets you easily define collision shapes for each of the tiles. I began by making the wall’s collision shapes match the entire space of the tile, but later would shrink this down in order to make line-of-sight more realistic.

Next I created a Player node that could be instanced onto this map. I implemented traditional eight direction movement using a tutorial from KidsCanCode. The technique outlined in that tutorial involves responding to directional input and then using a Raycast2D node to test whether there would be a collision in that direction. If there is not, move the character, otherwise do nothing.

Once I got that working I began tackling spell targeting. In most roguelikes, ranged attacks like spells will use some sort of selector to choose your target. The selector will often auto-target nearby enemies to make it easier to use, but in my case I relied on manual movement.

To get this working I had to create a new Target scene as an Area2D with the “X” as a Sprite, a CollisionShape2D, and a Raycast2D. I originally had a timer that caused the flashing behavior you see above, but later ditched that as it was hard to see where the target was at times. I hid the target by default, and then when the player pressed “Z” to cast their spell it would appear. The same raycast-based movement is implemented here in order to prevent the target from going through walls. Once the player has moved to their target and pressed “Enter”, the current position is sent back to the Player node using a signal.

From there I needed to make the spell casting actually do something. I decided the first spell I would implement would be a simple, single tile fire spell. This involved creating a simple scene that could be instanced when the spell is cast. In order to cause damage, I used groups. Groups are a simple way to share behaviors across sets of nodes. In this case, I added each entity that collided with the fire into a condition:burning group. Then, on each turn, I was able to get each entity that was marked as burning and apply damage to them.

Now that I could move around and cast spells, the next challenge was going to be adding actual enemies that could see and pursue the player. For that, I found another KidsCanCode tutorial that explained visibility and targeting using an example game with automated turrets. There are two parts to this: detecting when the player is within range and determining if the enemy can see the player. The first half is implemented by giving the enemy an additional Area2D with a circular collision shape as wide as their visibility range. If the player enters that circle, the enemy will attempt to target them. To determine if the enemy can see the player, we can use raycasts again.

You’ll notice that there are actually four separate rays. This is a trick that the tutorial gives to increase the accuracy of these line of sight tests. If you used a single ray to the center of the player, the game would consider them not visible when they are standing around the edge of a corner, even though logically the enemy could see them.

It was also at this point that I adopted a new raycasting technique that the tutorial mentioned. Instead of giving each entity a Raycast2D node (or multiple), it is more performant to get direct access to the 2d world state where you can perform as many casts from point A to B as you want.

So at this point we had enemies that know when they see the player, but have no way to actually pursue them. For this I had to implement a custom A* pathfinding algorithm. I had heard of A* before, but had never implemented it myself so this part ended up being really fun for me. For an in-depth explanation of the algorithm you can read through the blog post that I used to implement my version. The general idea is that you expand outward from the starting tile, generating a cost for each neighboring tile, until you reach your target. It is more efficient than Breadth First Search or Dijkstra’s since it will prioritize its expansion based on some heuristic function. The simplest heuristic (and the one I used) is the Manhattan Distance from the current tile to the target. In most cases this is going to get you the most efficient path rather quickly.

When an enemy sees the player it will calculate the best path to reach them. If they later lose sight of the player it will remember this path and move to the end of it, either regaining visibility of the player and calculating a new path, or stopping its movement.

I also added melee combat at this point. If the player or enemy try to move and collide with something that belongs to the opposite group, they will cause damage.

It’s almost starting to look like a game!

The last major change I made was to spell targeting. It’s not exactly fair if the player’s spells have infinite range and can be cast through obstacles. In order to remedy this I implemented a similar system to how enemies handle visibility and targeting. The spell target was given a circular area as its range and kept track of whether or not the player was within that circle. It also used raycasting to check whether it had line of sight back to the player. If both of those conditions were met, the spell could be cast. Otherwise, the cursor would turn red.

By the time I finished that it was about 11 pm of the last night of the jam. My very last additions were some improvements to the HUD. I added a heart sprite with a counter for the player’s health and implemented a simple combat log that displays messages such as when the player receives/causes damage, when enemies see the player, etc.

If you’re interested, you can play a web version of the game on my itch.io page.

Next Steps

Although it’s not quite a full roguelike yet, it has the skeleton of one. I’m planning to hopefully complete the game over time since there are still more things I’d like to learn how to implement.

In order to finish it I’ll need to add the following things:

Fog of war so the player can only see their immediate surroundings (and not through walls)
Procedural level generation
A mana/energy system for spell casting
Procedural enemies and items
More spells/conditions
A final boss

The one I’m most excited about is the level generation. I’m looking forward to learning some new algorithms related to maze generation.

Overall, I’m satisfied with the progress I was able to make during the game jam and I’m excited to see some of the other games that were completed. I had a lot of fun and hope that this is the beginning of a satisfying hobby of making games.

Advent of Code - Day 5 (Part 1)

Tue, 17 Dec 2019 20:47:00 -0600

The Day 5 puzzle heralds our (hopefully triumphant) return to intcode. We will be modifying our original intcode computer to handle a few new instructions as well as “parameter modes”. Up until now our computer implicitly supported a single parameter mode: position mode. This means that the value of a parameter tells you to look at that address (i.e. index) for its value. We will need to be able to support an additional parameter mode called immediate where the parameter itself is the value.

These modes are encoded directly in the instruction. For example, an instruction of CBAXX represents an instruction XX (such as 02 or 99) with three parameters where A is the mode (0 for position, 1 for immediate) of the first parameter, B the mode of the second, and C the mode of the third. Any leading zeroes can also be omitted with the assumption that they are mode 0, so the instruction 2, would have the same meaning as 00002. We can also assume that any parameters that involve writing/setting a value are in position mode.

In addition to parameter modes we will be supporting two new instructions. They are essentially a read and write that work based on an “input” value which is defined in the puzzle. The write instruction (opcode 03) takes a single parameter and writes the input value to that position and the read instruction (opcode 04) will output the value at the position of its parameter.

If we’re going to support these changes we’ll need to overhaul how we read instructions. Let’s start by attempting to decode the new instruction format and separate the instruction from the parameter modes.

(defun parse-opcode (opcode)
    (let ((opcode-list (pad-list-to-n (int-to-list opcode) (+ max-mode-length opcode-length))))
    (list (reverse (subseq opcode-list 0 max-mode-length)) (subseq opcode-list max-mode-length))))

This function is a little complicated but is easier to understand if we break it down into steps. Imagine we are parsing the 1002 instruction. We first use the int-to-list helper to turn it into (1 0 0 2). Since the instructions can omit leading zeroes for position mode parameters, we’ll want to add those back in so that we have a consistent format. The pad-list-to-n helper assists with that and turns the list into (0 1 0 0 2). Then we just divide the list up into modes and opcode and smash it back together resulting in ((0 1 0) (0 2)). The first list is the parameter modes and the second is the opcode. Also note that we’ve reversed the first list so that the modes are in the order of the parameters themselves.

To execute one of these instructions we’ll need to combine it with the parameters first. The goal here is to get to a point where we have an opcode along with pairs of parameters and their nodes. For example an instruction with parameters like 1002, 4, 3, 4 could give us something like ((0 2) (0 4) (1 3) (0 4)). Before we can combine the parameters with modes however, we will need to parse them out of the program.

(defun get-parameters (program ip opcode)
    (let ((num-parameters (- (instruction-size (list opcode)) 1)))
    (loop for index from (+ ip 1) to (+ ip num-parameters) collect (get-at program index))))

The function calculates the number of parameters to extract based on the instruction size. The 2 instruction has a size of 4 (one opcode plus three parameters). Using that value we can use the loop to collect the next N values starting at the current instruction pointer.

Now that we’ve parsed both the opcode and the parameters, we can attempt to put them together.

(defun get-instruction (program ip)
    (let* 
        ((opcode-and-modes (parse-opcode (get-at program ip)))
         (opcode (second opcode-and-modes))
         (modes (first opcode-and-modes)))
    (cons
        opcode
        (mapcar #'list modes (get-parameters program ip opcode)))))

The mapcar in the function is a neat little trick. Mapping list over multiple lists performs a zip of those lists. So if we hade modes (0 1 0) and parameters (4 3 4), it will neatly zip them together to get ((0 4) (1 3) (0 4)). We then combine that with the opcode to get the structure we laid out above.

We now have a way to retrieve the instruction at the current instruction pointer. All we have to do is update our instruction execution pipeline to handle the new format.

(defun execute-instruction (program instruction)
    (cond ((addp instruction) (execute-add program instruction))
          ((multp instruction) (execute-mult program instruction))
          ((writep instruction) (execute-write program instruction))
          ((readp instruction) (execute-read program instruction))))

(defun execute (program)
    (let ((ip 0))
        (loop
            (setf instruction (get-instruction program ip))
            (if (haltp instruction) (return 'HALT))
            (execute-instruction program instruction)
            (setf ip (+ ip (instruction-size instruction))))))

The big difference here is the last line of execute. Since not all instructions have the same number of parameters anymore we need to be able to advance the instruction pointer based on the size of the instruction executed.

In the execute-<instruction> functions we need to fetch the parameter values differently based on mode through the use of some helper methods. This is what the add instruction looks like now (along with the helpers):

(defun get-parameter-value-by-mode (program parameter)
    (let ((mode (first parameter)) (value (second parameter)))
    (if (positionp mode)
        (get-at program value)
        value)))

;; Sets are always performed by position so ignore mode
(defun set-parameter-value-by-mode (program parameter value)
    (set-at program (second parameter) value))

(defun execute-add (program instruction)
    (let
        ((input1 (get-parameter-value-by-mode program (second instruction)))
         (input2 (get-parameter-value-by-mode program (third instruction))))
    (set-parameter-value-by-mode program (fourth instruction) (+ input1 input2))))

The other instructions are implemented similarly. For the input value that the read/write instructions rely on I ended up just storing it as global state. I didn’t want to have to pass it through all of these other functions and I wasn’t sure of a better way to handle it. One idea I had was to have a top level computer function that encapsulated all of the other functions by defining them within itself. Any necessary state could then be set within that function and still used by the encapsulated function. In the end I abandoned this since the state makes it nearly impossible to run/test those functions independently.

My full solution can be found on Github.

Finalizers in C#

Mon, 16 Dec 2019 13:55:00 -0600

Similar to how programmers can use constructors to initialize an object, C# provides the concept of finalizers for cleaning them up. A finalizer declaration looks very similar to a constructor except it begins with a special ~ syntax and cannot take any arguments.

class MyClass
{
    ~MyClass()
    {
        // cleanup
    }
}

The purpose of finalizers is to perform additional cleanup related to the destruction of an object. Generally in C# the runtime will handle allocating and freeing memory, but if an object has any unmanaged resources (e.g. file handles, sockets, etc.) it will need to clean up after itself. The runtime is unable to do it automatically since it is not managing those native resources. Since most C# programmers do not find themselves dealing with unmanaged resources often, they usually do not need to implement a finalizer.

Finalizers and Garbage Collection

It is impossible to call an object’s finalizer directly. An object that provides a finalizer will be marked so that the garbage collector knows it requires a finalizer call. Once that object is no longer referenced the next run of the garbage collector will move it to the finalizer (f-reachable) queue. Objects without a finalizer are not added to this queue since they can be collected immediately. In addition, the object will be moved to the next “generation” of the managed heap.

The .NET garbage collector organizes objects into sets known as generations. All objects are created in Generation 0 and are moved up a generation each time they survive collection and collections run less frequently on the higher generations. This allows the garbage collector to focus on the most short-lived objects and free their memory more frequently.

After some time on the finalizer queue, a thread (separate from the main GC thread) will process items in the queue and call their finalizer. Each finalizer will implicitly call the finalizer of its base class so finalization occurs in an inheritance hierarchy chain from child to parent. After this point, the object will be removed from the queue and be available for removal on the next garbage collection.

It’s unclear why the finalizer queue is processed on a thread separate from the garbage collector but sources online seem to imply it is for performance issues. This seems reasonable since a garbage collection requires a pause of the application.

Deterministic Cleanup with `Dispose`

Since it is unknown when the finalizer will be executed the language provides another mechanism for deterministic release of resources. The IDisposable interface provides a Dispose method that can be called on an object explicitly to perform the cleanup that a finalizer would normally provide. A very common pattern for implementing IDisposable looks like this:

public MyClass : IDisposable
{
    private bool disposed = false;

    ~MyClass()
    {
        Dispose(false);
    }

    public void Dispose()
    {
        Dispose(true);
        GC.SuppressFinalize(this);
    }

    protected virtual void Dispose(bool disposing)
    {
        if (disposed)
            return;

        if (disposing)
        {
            // cleanup managed resources
        }

        // cleanup unmanaged resources

        disposed = true;
    }
}

The public Dispose method will be called by any consumers attempting to clean up an instance of MyClass. This will in turn call the protected helper Dispose(bool) which will perform the actual cleanup. This method has a few guards in it. First, a flag is checked in order to prevent disposal of the same resources more than once. Second, the value of disposing will determine whether to clean up managed resources (e.g. other objects that implement IDisposable) in addition to the unmanaged ones. When it is called from the publicly-exposed Dispose that flag is set to true since it should clean up all resources the object owns. However, when it is called from the finalizer disposing is set to false. If the finalizer is being called, the managed resources this object has may have already been destroyed and disposing of them again may cause issues.

The last part to point out is the call to GC.SuppressFinalize(this) at the end of Dispose. Since all of the resources have been manually cleaned up, there is no reason for the finalizer to run at a later time. SuppressFinalize will mark the object as not needing to execute a finalizer, allowing it to be cleaned up by the garbage collector without first waiting in the finalizer queue that was mentioned earlier.

The `using` Statement

Another benefit to implementing the IDisposable interface is the using statement. In order to ensure disposable objects get cleaned up properly a try/finally would need to be used.

void MyMethod()
{
    try
    {
        var foo = new MyDisposableClass();
        // do something
    }
    finally
    {
        foo.Dispose();
    }
}

The language provides the using statement as a helpful piece of syntactic sugar to simplify this.

void MyMethod()
{
    using (var foo = new MyDisposableClass())
    {
        // do something
    }
}

Everything in the using block will be wrapped in an implicit try/finally and disposed of before exiting the statement.

Most of the time programmers will not need to implement IDisposable themselves. A Dispose method (and finalizer) is only necessary when the class contains resources that are not managed by the runtime or contains other managed objects that implement IDisposable. While implementing this pattern is rare, it is important to understand when it is necessary in order to ensure that resources that are no longer needed get cleaned up properly.

Additional Reading

Advent of Code - Day 4

Wed, 11 Dec 2019 19:51:00 -0600

If the length of the puzzle description is at all correlated with difficulty, this one should be pretty simple. The goal is to identify “passwords” that meet specific requirements. The passwords must be six numeric digits long, each digit must be greater than or equal to the previous one, and there must be at least two adjacent digits that are equal to each other. For example, 122345 would be valid but 123456 and 123324 would not. We are also given a specific range of numbers to search as input.

The first thing we will want to do is split the numbers into a collection of digits in order to perform operations on them more easily. I figure there should be a simpler way to do this, but the best I found involved converting the number to a string, looping over the characters, and converting each individual character back to an integer.

(defun int-to-list (val)
    (loop for c across (write-to-string val) collect (digit-char-p c)))

Maybe not the most performant, but it will have to do for now.

We basically have two conditions that we need to test on all password candidates: that they increase left to right and that they contain at least one sequence of digits. Validating the increasing values can be done with a simple apply call.

(defun increasing (digits)
    (apply #'<= digits))

To validate that the potential password includes a sequence of matching digits we’ll first write a function that can determine all the sequences present in the value. Our goal is to take a list of digits as input and output a list of sequences. For example, (1 2 2 3 4 4) would return ((4 4) (3) (2 2) (1)). This can be accomplished via reduce with a lambda that performs the accumulation of sequences.

(defun split-sequences (digits)
    (reduce
        #'(lambda (acc digit)
            (if (equal (car (car acc)) digit)
                (cons (cons digit (car acc)) (cdr acc))
                (cons (list digit) acc)))
        digits
        :initial-value '()))

Let’s deconstruct that lambda with a few examples. Since we’re expecting a list of lists, the (car (car acc)) in the condition will be matching the current digit with the last one that was collected (or nil). So if acc equals ((2) (1)), then (car (car acc)) = 2.

Now imagine the next digit is also a value of 2. The condition will return true and we’ll follow the first path. Let’s see what it would look like if we resolved those forms iteratively.

(cons (cons digit (car acc))       (cdr acc))
(cons (cons 2     (car ((2) (1)))) (cdr ((2) (1))))
(cons (cons 2     (2))             (1))
(cons (2 2)                        (1))
((2 2) (1))

So acc would now be equal to ((2 2) (1)). If the next digit is a 3 we would follow the second branch of logic.

(cons (list digit) acc)
(cons (list 3)     ((2 2) (1)))
(cons (3)          ((2 2) (1)))
((3) (2 2) (1))

Now that we have a way of splitting the list of digits into a list of sequences we just need to test whether any of the sequences have a length greater than one. We can accomplish this with the help of a any function.

(defun includes-sequence-of-n (digits n)
    (any #'(lambda (x) (>= (length x) n)) (split-sequences digits)))

Finally, with our two test functions AND’d together and a loop over our input range we’re able to get our answer.

(defun test (password)
    (let ((digits (int-to-list password)))
    (and (increasing digits) (includes-sequence-of-n digits 2))))

(defun find-matching-passwords (begin end)
    (loop for password from begin to end when (test password) collect password))

(defun run ()
    (length (find-matching-passwords 147981 691423)))

The follow up exercise only requires us to change a single line of code. The new requirement is that the sequence of two matching digits cannot be part of a larger sequence. For example, 122234 would be invalid but 122333 would be fine.

In order to test this we update our includes-sequence-of-n function to require a sequence of exactly two digits.

(defun includes-sequence-of-n (digits n)
    (any #'(lambda (x) (= (length x) n)) (split-sequences digits)))

My full solution can be found on Github.

Advent of Code - Day 3 (Part 2)

Sun, 08 Dec 2019 20:26:00 -0600

I finished the second exercise and I definitely didn’t make my solution any faster like I said I might. I may return to it eventually but for now I’m still playing catch up on the challenges.

In the second part of this day’s puzzle they are switching up the distance calculation. Instead of looking for the intersection with the shortest Manhattan distance, we will now need to find the shortest “signal” distance. Basically, the intersection at which each wire’s path is the shortest.

We can measure this distance using the position function which returns the (first) index of a specific value in a list. We’ll also re-use our vector-equal function again for the comparisons:

(defun signal-distance (coords target)
    (position target coords :test #'vector-equal))
(defun combined-signal-distance (coords1 coords2 coordinate)
    (+ (signal-distance coords1 coordinate) (signal-distance coords2 coordinate)))

Then it is just a small change to swap out the Manhattan distance mapping for our own:

(defun run ()
    (progn
        (setf path-data (load-path-data "input.txt"))
        (setf first-path-vectors (convert-strings-to-vectors (first path-data)))
        (setf second-path-vectors (convert-strings-to-vectors (second path-data)))
        (setf first-path-coordinates (get-coordinates-visited first-path-vectors))
        (setf second-path-coordinates (get-coordinates-visited second-path-vectors))
        (apply #'min
            (mapcar
                #'(lambda (target)
                    (combined-signal-distance 
                        first-path-coordinates
                        second-path-coordinates
                        target))
                (remove-if #'(lambda (x) (vector-equal '(0 0) x))
                    (intersection 
                        first-path-coordinates
                        second-path-coordinates
                        :test #'vector-equal))))))

My full solution can be found on Github.

Matthew Herman

Printing Diagnostics in Neovim

Trying to Write

Creating a Persistent Terminal in Neovim

Functional Gift Wrapping

The Algorithm

An Imperative Approach

Towards a Functional Solution

Functional Gift Wrapping

Conclusion

.NET Core Tools

Creating .NET Core Tools

Using .NET Core Tools

Additional Reading

Seven Day Roguelike 2020

Getting Started With Godot

Entering the Labyrinth of the Lich

Time to Jam

Next Steps

Advent of Code - Day 5 (Part 1)

Finalizers in C#

Finalizers and Garbage Collection

Deterministic Cleanup with Dispose

The using Statement

Additional Reading

Advent of Code - Day 4

Advent of Code - Day 3 (Part 2)

Deterministic Cleanup with `Dispose`

The `using` Statement