DarwinBotsManual
Open the app EspañolES

How the port is built

The technical story of the port: the spec that described the original, the engine rewritten in C++ and compiled to WebAssembly, the two web interfaces, and how everything is tested and published.

This page is for anyone who wonders what is behind the app: where the engine came from, how it was rewritten for the browser, and how this site is put together. You don't need any of this to use DarwinBots (start with What DarwinBots is), but if you're curious, here is the whole map.

The original

DarwinBots was born as a desktop program for Windows, written in Visual Basic 6: a single executable holding the simulation, the editor and the graphics, with more than 53,000 lines of code. Carlo Comis created it in Italy in 2002 and 2003, and for over a decade its community kept it going: Purple Youko and Numsgil, Eric Lockard (EricL), the forum members and Botsareus. The version that runs here is 2.48.32, the last of that line. Who all these people are, with names and dates, is in Credits and license.

Visual Basic 6 is technology from another era: its programs no longer run on modern Windows. This repository exists so that the work of that community doesn't become inaccessible.

The port, step by step

The port was built in three steps, in this order:

  1. Understand and write the spec. Before writing a single line of the new engine, the original source was read line by line and described in full: the exact order of the cycle, the machine that runs the DNA, the 247 named memory addresses, the physics, vision, shots, ties, viruses, reproduction, mutations, the world and the file formats — and also the catalog of the original's bugs. That description lives in the spec/ folder of the repository.
  2. Rewrite the engine in C++. With the spec written, the engine was rewritten in C++20, subsystem by subsystem, and compiled to WebAssembly so it runs in the browser.
  3. The web. On top of the compiled engine came first the classic interface; then the new app that this manual describes; and finally this site, with the generated manual.

The order is no accident. Rewriting a 53,000-line engine “by eye” would have produced a simulator that was similar, not the same. The spec turned the question “what does this do?” into an answer you can verify before the port existed, and every piece of the new engine was written against it.

Today's architecture

The central piece is the engine: a C++ library with no interface, which doesn't know how to draw or touch the disk. It is compiled with Emscripten to a WebAssembly file (dbcore.wasm), a format that the browser runs on your own machine. For you that means three things: you install nothing, the simulation runs on your computer (not on a server), and both interfaces use exactly the same engine.

   Darwinbots2/  the original source (VB6, read-only)
         │    was read and described in
   spec/       the specification + the golden cases
         │    was rewritten in C++ and compiled
   port/core ─── Emscripten ──▶ dbcore.wasm (a single file)
                                    │ runs inside a Web Worker
                ┌──────────────────┴──────────────────┐
         the new app (/app/)               the classic one (/classic/)
                └── they share the wasm and the Bestiary ───┘

Outward, the engine exposes a small, explicit API: create a simulation and advance it cycle by cycle, set the parameters, seed species, request the state of everything so it can be drawn, save and load. Files (see File formats) travel through memory, not through the disk: the engine packs and unpacks the bytes, and whoever calls it decides where to store them.

The simulation runs in a Web Worker, a separate browser thread: no matter how heavy the cycle is, the page never freezes, and each frame reaches the interface as a single buffer ready to draw. The project's rule is strict: the presentation layer never recalculates physics or randomness, it only shows what the engine dumps. That is why the new app and the classic one, however different, give identical runs.

On top of the engine there are two interfaces. The classic one was the first web version: closer to the original program and in English; today it is frozen and published at /classic/ (see The classic interface). The new app is the one this manual describes: in Spanish and English, with runs, analysis, an editor and tournaments (see A tour of the app). Both share the same wasm and the same Bestiary: the community's bots, indexed with their profile and genes, which the library offers for seeding (see Bots: library and profile).

The manual you're reading is generated too. The pages are written by hand, but the entries for each sysvar, each operator and each parameter come from the spec data, and a Node generator produces static HTML: each page is a file you can read without JavaScript. Only the search box and the theme switch use a few dozen lines. The manual's DNA blocks are colored with the editor's highlighter, pass the same lint as your bots, and carry two buttons: Open in the app, which takes you to the editor with that DNA already loaded, and Copy, to paste it wherever you like.

The spec, arbiter of the port

The spec is not courtesy documentation: it is the contract. It was written from the original source and before the new engine, with a golden rule: the source is the spec. No interpreting from memory or turning to the wiki; when in doubt, you went back to the source. And the original source is read-only: it remains intact in the repository, as the final authority for any tiebreak.

Its main tool is the golden cases: tests with the exact expected result, written before the implementation of each subsystem. The workflow was always the same: the golden case red → the implementation, transcribed from the source citing the lines → the case green → only then, commit. The cases range from Visual Basic's banker's rounding to the global order of the random draws within a cycle, and the whole suite is run on three different builds of the engine. And when the spec itself had an erratum, the spec didn't win: the source won, and the spec was corrected.

How we check it's right

How it is built and published

The darwinbots-wasm.org site builds and publishes itself, on every push to the main branch:

  1. The engine is compiled to WebAssembly — just once: both interfaces share the same file.
  2. The new app is built and the manual is generated. If anything fails — a broken link, a DNA block with warnings — there is no site.
  3. The complete package is assembled: the home page, /manual/, /app/, /classic/ and the wasm in /build-wasm/.
  4. It is published to Cloudflare Pages, which serves the domain.

The publishing secrets live in GitHub, in an environment that only accepts deployments from the main branch; nobody uploads anything by hand. Changes arrive through PRs: the repository is public, anyone can propose their own from their copy, and CI tests all of it before it is merged.

If you want to look at the work up close, the repository keeps the three layers in order of derivation: the untouched original source, the spec that describes it, and the port that implements it. This manual, the app and the engine you download when you open the site all come from the same tree.