Drivers

Each player in Hadronize is controlled by a Driver, which is basically just a function that takes the current game state as an input and outputs a player. I implemented drivers on like day #2, but I don’t think I’ve talked about them in a devlog yet.

• The first driver I made is the dogpile driver. It’s logic is extremely simple: it just selects the player who goes first. It doesn’t even reference the game state at all. If every player is a dogpile driver, this means that everyone just dogpiles onto the first player and ends up stealing basically all of its quarks before it can use them. This is obviously a terrible strategy because it’s not even capable of trying to score, but it was very simple to implement and I use it as a placeholder.
• The second driver I made is the rng driver. It just makes random decisions. However, because I insist on everything being deterministic, it can’t just use Math.random. Instead, it stringifies the game state, converts that string into a 32-bit integer via a djb2 hash, then uses that integer to seed a mulberry32 pseudorandom number generator, then uses the output of the mulberry to make its player selection.
• The newest driver that I just finished developing is the expected value driver. It does actual strategic calculations to determine what the expected value of choosing each player would be based on the information it has available, then selects the player that maximizes that value.

Next Steps

I’ve started building the UI, but I’ve still been procrastinating on actually working on it in earnest. I should probably do that.

Tests and CLI Args

You can now add arguments to the Hadronize CLI in the terminal, which lets you avoid having to use the setup flow. Here’s an example.

pnpm run cli --seed 12345 --player Alice:human --player Bob:bot

It also works if you run the CLI as a remote script.

deno run -A http://ethmarks.github.io/hadronize/cli.ts -s 8 -p a:bot -p b:bot -p c:bot

This was pretty easy to implement. I just used Node’s parseArgs utility for the main arg parsing and wrote a bunch of validation logic that converts the raw arguments (which are always strings) into the data types that my code uses.

Tests

Over the past couple days, I’ve made a little test suite for the game logic using Vitest. I’ve written 19 individual tests, but some of them repeat multiple times with different game seeds and whatnot to ensure that it works with a variety of inputs, so Vitest actually runs 101 tests in total.

All of the tests pass, and I didn’t discover any bugs, which either means that I managed to get all the game logic correct on the first try, or that there’s something wrong with my tests.

Next Steps

I think that I’ve probably spent too much time on the CLI. I don’t think that it was time wasted, but I probably ought to get started on the main game UI.

CLI Remote Script

You can now run Hadronize CLI in a terminal without cloning the repo. If you run the command below, Deno will automatically fetch all the dependencies.

deno run -A http://ethmarks.github.io/hadronize/cli.ts

Node doesn’t support remote scripts because it lacks Deno’s awesomeness, but because of the Deno binary on npm, you can run Deno (and therefore Hadronize) through any of the other package managers!

npx deno run -A http://ethmarks.github.io/hadronize/cli.ts
pnpm dlx deno run -A http://ethmarks.github.io/hadronize/cli.ts
bunx deno run -A http://ethmarks.github.io/hadronize/cli.ts

For example, in the attached screenshot, I SSH-ed into one of my home servers that hadn’t cloned the Hadronize repo nor installed Deno, and tried to run Hadronize as a remote script via pnpm. After resolving dependencies for a few seconds, it ran flawlessly.

How it works

I first encountered Deno remote scripts in Lume’s init command, and my implementation is heavily inspired by it. Basically, all that the cli.ts file does is fetch the CLI code from JSDelivr, which fetches it directly from the GitHub repo. From there, Deno is smart enough to resolve all of the CLI code’s dependencies and run it.

Compatibility

Before today’s changes, running Hadronize via Deno worked perfectly fine. deno task cli behaved identically to pnpm run cli. However, that’s because Deno has an automatic Node compatibility layer, not because Deno can actually run the code natively. That compatibility layer doesn’t really work with remote scripts (because Deno can’t find the package.json), so when I first tried to run the remote script while developing it, it crashed and burned immediately. This was because, without the compatibility layer, Deno and Node handle things fundamentally differently. There were several differences, some of which I expected and some of which I didn’t, but the easiest one to understand is NPM imports.

NPM imports

My CLI code relies on the picocolors library for getting ANSI escape codes. When I was first writing the code, I added the picocolors package via NPM and imported it in the normal Node way:

import pc from "picocolors";

The problem is that Deno can’t parse bare imports like that. Deno expects this format, which Node cannot parse:

import pc from "npm:picocolors";

I tried configuring an import map in deno.json, but it didn’t work. I considered just hardcoding the ANSI escape sequences, but I decided that I would need to figure out how to polyglottally import NPM packages in both Node and Deno at some point, so I might as well figure it out now.

My solution was to create a deps/picocolors.ts file to proxy the picocolors import by dynamically importing it based on whether it’s being run in Deno or not:

const { default: pc } =
  "Deno" in globalThis
    ? await import("npm:picocolors")
    : await import("picocolors");

export default pc;

NPM imports were only one of the issues that sprung up. Frustratingly, the only way to test whether or not a solution worked was to commit, push to main, and test on production. The whole Deno compatibility saga required 12 commits in total.

Next Steps

I’m still working on writing unit tests for the game logic. I already have a few tests, but they’re definitely not comprehensive. I’ll write a devlog about the tests once I’m finished with them.

Setup Flow

diff from last devlog to this one

Since my last devlog, I added a flow that lets users set up each game before starting it. The setup includes specifying the seed, player count, the names of each player, and whether each player should be a human or a bot. I made it work in three different formats, each of which had to be implemented individually:

• The terminal: at its core, this format is just a normal TUI. It prints input prompts, awaits the user’s input using the abstracted NbrInputFunc I mentioned last time, and repeats this until the user provides an input that passes the validation function. Pretty standard stuff.
• The browser console: I used the same trick that I described last time to allow users to enter their input via the browser console. It creates a custom window property that resumes execution, then halts execution with a Promise<void> until the window property is called. Unfortunately, it wasn’t possible to use the anonymous getter trick that I used last time. If I did that, I would have to create custom window properties for every possible 32-bit number to allow user to enter the seed, and create custom properties for every possible string to allow users to enter player names. That obviously wasn’t possible, so instead I just created a window.r function that takes any input type. The “r” stands for “respond”. To set the seed to 42, you type r(42) into the console, which is a reasonably clean UX, I think, though not as clean as just typing 42 like you can in the terminal.
• The webpage: this uses HTML <input>s and SvelteKit’s reactivity. The trickiest part was navigating the fact that the value of one of the inputs (player count) controls the structure of some of the other inputs (player configs). At first I tried writing code to dynamically construct a variable-length Array, but that was a nightmare of complexity. Then I tried making all 6 possible player configs visible all the time and just adding the “Disabled” type, but that made the UI look ugly and was also kind of complicated to implement. The solution I settled on was to internally use an Array with a fixed length, automatically hide the player config UI elements with an index less than the player count value, and slice the player config Array before passing it into the main game function. I think that this solution is the best of both worlds while also being fairly simple to implement.

Next Steps

I know that I’ve been saying this for the past 4 days, but I need to write some internal docs for my game logic code and write tests. I haven’t noticed any bugs during my playtests while building the CLI, but I’d like the peace of mind to be fairly confident that I’ve implemented my game rules correctly.

Browser CLI

Since my last devlog, I implemented a CLI for Hadronize that works across Node, Deno, Bun, and browsers. You can try it out by visiting https://ethmarks.github.io/hadronize/cli or running the following commands (you only have to run one of the Node/Deno/Bun commands):

# Clone the repo
git clone https://github.com/ethmarks/hadronize.git
cd hadronize

# Run with Node (via npm or pnpm)
npm install
npm run cli

# Run with Deno
deno task cli

# Run with Bun
bun install
bun run cli

Link to the diff between last devlog and this one

Abstraction

In case you’re not familiar with the JS ecosystem, a cross-runtime CLI like this is not normal. My CLI uses styled text, but the different runtimes have different ways of logging styled text. Node, Deno, and Bun all use ANSI escape characters, but browsers use %c placeholders (Deno also supports %c because Deno is awesome, but none of the others do). Node uses the readline API to get user input, but Deno and Bun both use prompt(), and browsers don’t even have a way to get user input without clever tricks (as you’ll see later).

My solution to the styled text problem was to create a custom micro-library which I call styledLog.ts (or sl for short) which invents an easy-to-use syntax for rich-text logging called slChunk, then automatically detects if it’s running in a browser and renders slChunks with either ANSI escapes or %c placeholders accordingly.

Cross-runtime user input

My solution to the user input problem was a little less elegant, but in my opinion it’s much cleverer. Node, Deno, and Bun were the low-hanging fruit. All I had to do was create an abstracted NbrInputFunc() function that automatically detects which runtime is running the code, then switches out the method it internally uses to fetch input accordingly. Easy.

But implementing a CLI in the browser was a lot more tricky. I could have just used the window.prompt() method, but that opens a disruptive pop-up window that looks terrible. Instead, my code dynamically adds custom properties to the window object, then halts the script execution via a Promise<void>. Each custom property is named after a player name and has an anonymous getter function. When you type a player’s name (e.g. alice) in the console, it automatically evaluates window.alice, which triggers the getter. The getter sets the userInput variable then resolves the frozen Promise to resume execution.

I hope that made sense. It’s a really hacky solution, but it does work, and it provides an elegant input syntax that resembles that of terminal CLIs. My first idea (which is still used as the fallback) was to just define a window.turn() function, so you would enter your input with turn("alice"). The current solution is much more elegant, in my opinion, because the user doesn’t need to type parenthesis or quotes.

Here’s a link to the code if you want to check it out for yourself.

Beginnings of the UI

I also started working on the UI the tiniest bit. Not anything that’ll make it into the final version, mind you, but I added a page that demos the Hadronize CLI. It seemed wrong to make the demo page blank and not include instructions, so I wrote some. It seemed wrong to use unstyled bare HTML, so I added holidaycss.

Next Steps

I think that there’s still some work I need to do in the game logic and CLI before I start working on the UI. The CLI demo currently doesn’t have any way to customize the game settings (e.g. how many players there are and what deterministic seed to use), so I’ll probably work on that next.

Thanks for reading!

Core Game Logic

Today I implemented most of the core game logic in TypeScript. My code is pretty messy, probably has some bugs, and definitely has some idiosyncrasies that I should add docs for, but it does work correctly. Mostly. Here are a few highlights from today:

Determinism

The rules specify that quarks are created on-the-fly at the start of each turn, and that it’s impossible to predict what flavor a superposition will collapse into. Nondeterministic code makes me uncomfortable, so I decided to cheat a bit behind the scenes to make the whole thing pseudorandom and fully deterministic. In the game constructor, every quark that will ever be used during the game is pre-generated based on values from a mulberry32 function, then the collapsed flavor is predetermined ahead of time. Those two things: the list of future quarks that will be “created” on subsequent turns, and the flavor that each superposition will collapse into, are secret information that the players aren’t allowed to know, which means I have to be careful to sanitize the game state before it’s given to players.

I hate references

So, one of the first things that I did was create the Quark class. It has a few methods, but mainly it’s just a DTO for a flavor and a superposition. So my original plan was involved doing normal OOP and having each quark be owned by a Player class or the Game class itself. But once I actually started coding it, I remembered that I hate having to remember what’s stored as a value and what’s stored as a reference in JS. This is especially annoying when moving quarks between containers. So instead, I decided to just store an array of every extant quark, including not only a flavor and superposition but also an index. When a player class “owns” a quark, it really just owns that quark’s index number which corresponds to a quark in the game class’s SSoT. Crucially, the index number is a simple integer that doesn’t have any of JS’s object reference silliness.

Timeline

I decided that the game class should save every past state that it’s been in for some reason. I might use it in the UI to let users scroll back in time to see how the game played out, or maybe use it to make neat statistics at the end of the game, or something like that. It might also be useful for bots (more on that in a future devlog). But anyways, actually implementing the timeline was extremely frustrating, mainly due to Typescript. The final implementation that I settled on is pretty clean, but it was not my first thought, and I went through maybe a dozen different iterations over the course of an hour.

Next Steps

I’m probably going to spent a bit more time in the game logic before starting work on the UI. As I mentioned, I need to write docs for the idiosyncrasies of my code because otherwise I’ll forget how it works and that’s how bugs happen. Speaking of bugs, I’m sure that there are a few in my code, so I’ll probably write some tests to try to find them.

Thanks for reading!

Hadronize

This is my first devlog for this project. It’s a multiplayer strategy game that you can play in your browser.

https://github.com/ethmarks/hadronize

Basically the only things that I’ve done so far are write the rules in the README and brainstorm a bunch. The rules are pretty important, so I’ll write them in this devlog. Because there’s a 4000-character limit to Stardance devlogs, I’m going to try to keep the rules shorter and less thorough than I did in the README.

Rules

Hadronize is a 2-6 player game which will probably take about ~10 minutes per game.

• The goal is to be the first player to hadronize 10 or more quarks.
• Quarks are basically the cards. There are 6 different flavors of quark: up, down, strange, charm, bottom, and top. By the way, I’m not making that part up.
• Quarks start out as Superposed Quarks, which are quarks in a state of superposition between three different flavors. Once the superposition collapses (more on that later), it chooses one of the three flavors in its superposition and becomes a normal quark with a single flavor.
• Each player starts with four collapsed quarks with randomly-chosen flavors in their respective cloud chamber.
• On each turn, a new superposed quark appears. The players know that the quark will be one of the three flavors in its superposition, but they don’t know which one. The player whose turn it is (aka the active player) will choose any player (including themselves) to be the observing player. The observing player observes the superposed quark, which collapses it and adds it to their cloud chamber.
  • If the observing player has none of that flavor (e.g. the new quark collapsed into charm and the player only has down quarks), then nothing else happens and the turn ends.
  • But if the observing player does have at least one quark of the same flavor, something does happen.
    • If the active player chose themselves to be the observing player, the new quark reacts with all existing quarks of the same flavor, and they all hadronize together.
    • If the active player chose a different player to be the observing player, the new quark reacts with all existing quarks of the same flavor, and they all quantum tunnel from the observing player’s chamber into the active player’s chamber. In other words, the active player steals some of the observing player’s quarks.

If my explanation is unclear, check out the README because I probably explained it better there. If the README is unclear too, feel free to let me know by commenting on this devlog or opening an issue or whatever.

Mantis

If the rules sound familiar, it’s because I mostly just stole them from the card game Mantis by Exploding Kittens. My original idea was to just create a digital version of Mantis, but I was concerned about running into copyright trouble if I called it “Mantis” and used the same terminology and whatnot. Game mechanics can’t be copyrighted, but names and terminology absolutely can. I considered just making my game about abstract colors, but then I suddenly realized that making it about quarks would fit really well, so I did that instead. I did make a few changes to the core mechanics (e.g. using 6 flavors instead of 7 colors, and combining “scoring” and “stealing” into “observing”), but it’s still basically just a reskin of Mantis.

Next Steps

The next thing I’m going to work on is actually implementing the rules in TypeScript. After that I’ll probably work on the UI.

P.S. I also spent like an hour making a terrible-looking banner for Hadronize to use as the Stardance project image.