Harvester: a Godot space mining demo where the pirates are steered, not scripted

A game loop you can describe in one sentence

Harvester is a top-down 2D space mining game built in the Godot engine, written in GDScript. The premise is a resource loop: you fly out into an asteroid belt, dock with asteroids to mine iron, dock back at your station to deposit it, and spend the proceeds on upgrades.

The README's summary section is unusually precise about how that plays out. The player starts with a ship at the space station on a relatively large procedurally generated map filled with asteroids. Asteroid pockets are scattered around the map and separated by distance, and each asteroid holds a finite amount of iron. Once emptied, an asteroid vanishes, and new ones spawn on a timer to refill the empty gaps. That timer is what makes the map feel alive rather than depleting.

The pressure comes from escalation. Each time the player deposits a certain amount of cargo, pirates spawn around some of the asteroids. The README is explicit about the design intent: this forces the player to take different routes until they can destroy the interlopers. The run ends when the player is overwhelmed by mounting difficulty and growing opposition, and the score is how far they got. There is no win state, which is the honest shape for a score-attack arcade loop.

Controls and the one idea worth stealing

The control scheme is small. In travel mode, `A` and `D` rotate the ship while `W` and `S` thrust forward and back. That is Newtonian rather than tank-style movement, so momentum is a constant consideration. Shooting is the spacebar, and the README notes the ship has energy guns that can become stronger through upgrades. `M` opens a navigation map showing where asteroids and pirates are.

The interesting binding is `E`, which activates docking mode. Near an asteroid or the station, pressing it hands control to an AI that steers the ship into position and locks it in place. Automatic docking is unusual in a game with Newtonian movement, and it exists here because the alternative is a fiddly alignment minigame that would interrupt the resource loop on every trip.

That single key is the clearest piece of design in the project. The player decides when to dock, the game handles the precision. If you are reading this for ideas rather than to play, that is the one to lift.

The upgrades are gated behind a deposit threshold. Filling the station's bar to 100% lets the player choose from health, speed, rotation speed, cargo space and weapons damage, so every run trades off between survivability, throughput and firepower.

Pirates that chase, hold range and go home

This is the part of the project that justifies the repository existing at all. The README's development section notes that the game uses the Godot Steering AI Framework, a separate GDQuest repository, and the pirate behaviour section describes what that produces.

The described pirate behaviour has three parts. They move in precision mode, they chase the player and get within weapons fire range but not too close, and they avoid asteroids so they do not crash into them. Once the player is out of range, they steer back to their spawn point.

Each of those four behaviours is a steering problem rather than a scripted path. Holding a firing distance is the classic pursuit-with-spacing case, where a naive chase makes enemies pile into your face and an unscripted wander makes them useless. Returning to a spawn point after losing the player is the behaviour most hand-written implementations skip, and having it here means a pirate you escape from stays escaped rather than teleporting back into danger.

The project description and repository topics both list artificial intelligence and steering behaviors, which tells you the AI is the subject of the demo. Read the pirate script first. It is where the framework's actual usage lives.

Why this repository is shaped the way it is

The repository is tiny by design: a `LICENSE` file, a `README.md`, a `CHANGELOG.md`, an `img/` directory and a `project/` directory holding the Godot project itself. There is 1105 stars and 135 forks, 17 open issues, and the default branch is `master`.

The contributing section is the part that reveals intent. Alongside an issue link for bugs, it points at two documents: GDQuest's contributor guidelines and their GDScript style guide. For a game demo, requiring a house style guide is a strong signal about what kind of codebase this is meant to be. It is a reference implementation that also happens to run.

The release history supports that reading. There is a single tagged release, `v0.1.0`, named Harvester: 2D Space Game 0.1.0 and published on 2020-03-05, which describes the first release as bringing the full base game loop with a controllable ship, mining, pirate squads and upgrades. One release, described as a first release, for a teaching project. The repository is not archived and the last push was on 2026-05-16.

One licensing caveat is worth flagging directly. The repository's license field is not declared, even though a `LICENSE` file is present in the tree. If you plan to reuse the code or the art in something of your own, read that file before you do rather than assuming MIT.

A Godot 3.2 project in a Godot 4 world

The release notes for 0.1.0 describe Harvester as made with Godot 3.2. That single fact determines how you approach opening the project today.

The Godot 4 migration was not a version bump. It replaced the rendering backend, replaced the input and physics APIs, reworked nodes and scenes, and changed GDScript in ways that break existing scripts. A project built against 3.2 will not open in a current Godot editor and run cleanly, and the fixes are not mechanical in every case.

So there are two sensible paths. The first is to open it in a Godot 3.x build and read it as-is, which is the cheapest way to see how the steering framework is wired into a real game. The second is to treat the repository as a reference and rebuild the interesting pieces in a current engine, porting the AI behaviour rather than the whole project. The second is more work and produces something you can actually build on.

The GDQuest Steering AI Framework is a separate repository, so the dependency is easy to inspect on its own. Reading that framework alongside the pirate script is a more focused way to learn the technique than reading either alone, since the game shows the problem and the framework shows the solution.

What the project is and is not for

It would be wrong to describe Harvester as a game worth playing for long. The loop is one verb deep once you have done it three times, the art is functional, and there is no progression beyond the upgrade bar. Nobody is recommending this as a game.

As a codebase to read, it is considerably better. It is small enough to hold in your head, it solves a specific AI problem in a visible way, it ships with screenshots showing mining and explosion moments, and its structure follows the team's own published GDScript conventions. That combination, complete game plus separated AI library plus documented style, is rarer than it should be.

The economics are also worth understanding before you dive in. The README is explicit that the work on this free software is sponsored by GDQuest's Godot game creation courses, and it repeats the pitch for those courses at the top of the page. That is not a criticism, it is how the project funds itself. It does mean the demo is a recruiting artifact as well as a teaching one, and that the courses linked from it are the more complete treatment of the same material.

If you are working in Godot and want to see steering behaviour applied to something more interesting than a moving circle, this is the shortest reasonable path to that.

Editorial conclusion

Harvester earns its place as a teaching project rather than as a game to finish. The loop is four verbs: find an asteroid pocket, dock, mine, return. What makes it worth an afternoon is that the pirates are not scripted, they chase, hold range, avoid asteroids and return to a spawn point using GDQuest's separate steering AI framework, so the repository teaches a technique rather than a game loop. Two limits are worth knowing before you start: the 0.1.0 release notes describe the game as built with Godot 3.2, so it targets a Godot generation that is no longer current, and the repository declares no license field, which is a real question if you intend to reuse the art or code. Clone it, run the mining loop, then read the pirate and docking behaviour to see how a small steering framework replaces a state machine.

Frequently asked questions

Official sources

1. gdquest-demos/godot-2d-space-game on GitHub
2. Issues
3. README
4. Releases