Let’s Play Screeps (Part 1)

Previous post.

Screeps is a tower defense game that takes commands from players programming JavaScript. Dox-populi offers a tangible example of how we might build an infrastructure that lets us work productively in domains where we haven’t yet built professional experience. Each dox-populi tutorial is modeled after the original screeps tutorial.

Along the way, you’ll work your devflow muscles by familiarizing yourself with the process of creation, verification, and deployment. By the end, you’ll have a working colony to improve and extend. The first tutorial will get you started with dox-populi.

You’ll get a Screeps colony to play with and exercises to test both your understanding and the project’s premise: Can the LLM use the structure of the project to facilitate a previously unattenable level of productivity with tools that would otherwise be out of reach?

The shape

I encourage you to either install the nix daemon, or a full install of detnix. But if you’d rather not, I’ve provided an image with a prebuilt environment.

In the VM:

• dox/creeps.dox, The llm-written spec. Paradox checks the spec for internal consistency. Only validated specs generate TypeScript.
• harness/main.ts and harness/role.harvester.ts. The TypeScript harness that makes the game calls, using that generated logic.
• A game server and a browser viewer.
• An install of detnix, with various tooling available in the devShell.

By the end you will have:

Edited every layer of the stack - The spec, - The TypeScript harness, - the tutorial’s JS Investigated a live server using the viewer, its console, and room-feed. As well as having pushed each change through the deploy pipeline.

Before you begin sets up your environment and the working method: your agent’s answers are claims, the instruments in the flake produce the evidence, and you decide. Read it before the first exercise.

Start

Follow the README.

Bring your discernment

The promise of the new technology is one of access and velocity. However we are still required to keep our hands in the code. I believe llm agents make this possible in a way that lets us confront code and systems we might otherwise be unable to manage productively. Bring your curiosity and bravery to these exercises and have fun with the process. We’ll discover it together.

Every exercise asks you to commit before you look: to a written prediction, a question, or a change you intend. Then the run produces the evidence, and you hold the two together. Where an exercise asks for a prediction, make a note. When the room disagrees with your note, the note is what makes the miss undeniable.

The server

nix run .#server --builders '' starts the open-source Screeps server.

Get in the mix — refactoring. Is the klanker British? It certainly does appreciate verbosity. Why write one app when two will do? You can help out though.

The deploy

nix run .#deploy-local --builders '' reads dox/creeps.dox, Paradox verifies the spec’s named properties and generates the decision logic, tsc typechecks the harness against that generated code, and the bundles land on the server as main.js and role.harvester.js. From then on the server calls that code every tick.

Get in the mix — the API. The deploy landed; the server can report what landed. Sign in with curl, find your room, watch the room feed, and read your creep’s diary.

The client

nix run .#client --builders '' point your browser to http://127.0.0.1:8080/

The browser client has several features. First is the map on the left, and the metadata panel on the right. Below that you’ll find two tabs: the console and the code delivered from the client generator. The code you just deployed is running every tick. This is where you watch it work.

Get in the mix — the client. You can use your agent to explore and modify the viewer’s typescript.

A note before proceeding

Be sure to rm -rf ./server-data before each exercise.

Breaking the spec

So far the gates have said yes to everything you shipped. Time to hear them say no — break the spec, break the harness, and see if the rejection you predicted is the rejection you get.

Picking a source

Two sources, one creep, two ways to choose. Work out each program’s pick before its harvester walks. Then move the spawn to see the difference in the pick.

Turn-around threshold

Make the colony worse on purpose and watch every gate say yes. Then write the test that says no.

Klanker slop

The klanker writes slop, but you can clean it up a bit.

What you just did

You got the game running and got in the mix. This is what software development is all about: getting your hands dirty, learning by doing, and figuring out how to make things work. You touched all the parts of the development workflow. Tutorial two keeps the momentum going. I’ll link here when it’s ready.

Also

dox-populi is an experiment. I’ve presented a lot of dense information in a way that is meant to be accessible and engaging. The goal is to create a space where people can explore complex ideas without feeling overwhelmed. How did tutorial-one go for you? Let me know on X or gitlab. I’m lambdafan.

Also Also

Found something broken or missing? Help the next person by filing an issue or a merge request;