Both need to agree on what exists in the game. Items, skills, gathering nodes, crafting recipes, etc. If I define an Iron Sword, the server needs its stats and equipment slot for combat math, while the client needs its name, icon, and stat bonuses for the inventory screen. If those definitions drift apart, the game breaks in annoying ways.

A third system reads the same definitions: the public wiki on this site, which has a page for every item, skill, node, and recipe.

I needed one source of truth. I call it the static-db.

flowchart LR
    YAML[("static-db<br/>(YAML)")] --> Server["Go Server"]
    YAML --> Client["Godot Client"]
    YAML --> Wiki["Next.js Wiki"]
    Server --> DB[("PostgreSQL")]
    Server --> RAM["In-Memory Registries"]
    Client --> TRES[".tres Resources"]

The Static DB

The static-db is a directory of YAML files. Every game entity gets a folder with an entry.yml and, optionally, an icon.png:

static-db/database/
├── items/
│   ├── ingots/
│   │   ├── bronze/
│   │   │   ├── entry.yml
│   │   │   └── icon.png
│   │   └── iron/
│   │       ├── entry.yml
│   │       └── icon.png
│   └── equipment/
│       └── weapons/
│           └── swords/
│               └── iron/
│                   ├── entry.yml
│                   └── icon.png
├── skills/
│   └── smithing/
│       └── iron-platebody/
│           └── entry.yml
├── nodes/
│   └── trees/
│       └── oak/
│           ├── entry.yml
│           └── icon.png
└── stations/
    └── smithing/
        └── anvil/
            ├── entry.yml
            └── icon.png

This is the real entry for the Iron Sword:

id: 019bcddd-9931-7acd-92d1-3fbbccc161c8
name: Iron Sword
tier: 2
prerequisites:
  combat_level: 12
short_description: A humble sword, suited to any battle.
long_description: >
  Forged from @items/ingots/iron, this sword is a reliable
  weapon for any warrior. The blade is balanced and sharp,
  ready to strike true in combat.
item_slot: mainhand
common_stats:
  attack: 10
  agility: 4
  strength: 2

A few things are happening here.

• The id is a UUIDv7, generated once and used as the primary key wherever the item is persisted.
• The path under items/ (equipment/weapons/swords/iron) becomes its slug, used in database queries and client lookups. Wiki URLs and YAML @ references keep the items/ prefix.
• The Iron Ingot (@items/ingots/iron) in the description refers to another static-db entry.

Note: This dev journal and wiki render @ references as inline wiki links. The Iron Ingot & Iron Sword above are live examples.

Gathering nodes work the same way. Here's an Oak Tree:

id: 019f86ea-63aa-7ff9-8380-ad79a8fca5d7
name: Oak Tree
tier: 2
short_description: >
  A broad, sturdy hardwood with dense golden-brown timber.
long_description: >
  Oaks grow slow and strong in the richer soil of the larger
  isles, yielding @items/logs/oak. Their dense grain rewards
  a woodcutter with patience and a well-swung axe.
inspect_description: An Oak Tree with a broad, sturdy trunk.
prerequisites:
  woodcutting_level: 7
drop_table:
  - item: "@items/logs/oak"
    chance: 100
    quantity:
      min: 1
      max: 3

Crafting recipes connect those entries. This is the smithing recipe for Forge Iron Platebody:

id: 019bcde1-9b09-7294-bd68-21344182f886
name: Iron Platebody
tier: 2
level: 12
experience: 100
station: anvil
station_category: iron
rarity_eligibility: with_suffix
short_description: >
  Craft a heavy plate body armor from Iron ingots, providing
  excellent protection.
long_description: >
  A smithing technique that crafts @items/ingots/iron into a
  @items/equipment/chestpieces/plate-body/iron.
icon: "@items/equipment/chestpieces/plate-body/iron"
crafting:
  crafting_time: 5
  materials:
    - item: "@items/ingots/iron"
      count: 5
  produces:
    - item: "@items/equipment/chestpieces/plate-body/iron"
      count: 1

The crafting block says which materials are consumed, what gets produced, how long it takes, and which station it uses. The @ references in materials and produces point to other entries. The whole graph is plain YAML.

Those references chain together into a graph, with recipes as the edges: each one consumes some entries and produces another. The platebody recipe above is a single branch off the iron ingot, which every iron recipe in the smithing tree draws from:

flowchart LR
    Deposit["Iron Deposit"] -->|"drops 1-3"| Ore["Iron Ore"]
    Ore -->|"2x"| Ingot["Iron Ingot"]
    Ingot -->|"1x"| Gloves["Iron Plate Gloves"]
    Ingot -->|"2x"| Helmet["Iron Plate Helmet"]
    Ingot -->|"4x"| Shield["Iron Plate Shield"]
    Ingot -->|"5x"| Plate["Iron Platebody"]

Three Consumers

Three systems read the same YAML and do different things with it.

The server reads the static-db in two ways. On startup, the sync code walks every entry.yml under items/, parses the YAML, and upserts each row into PostgreSQL by UUID. Gathering nodes, crafting recipes, and stations go into typed Go registries that stay in memory for the life of the server process. When a player chops an Oak Tree, the server looks up oak in the tree registry to get its drop table and skill requirements.

Bash build scripts compile the same YAML entries into Godot .tres resource files for the client. They walk the static-db, copy icons into the asset directory, and emit resources that Godot can load directly. If I change an item's name or stats, I run make build and the client picks it up.

The wiki is the simplest of the three. It reads the YAML directly at build time, with no intermediate compilation step. The Next.js site walks the directory tree, parses each file with js-yaml, and renders pages from the data.

When I add a new item, I write one entry.yml file and everything else picks it up.

Schema and Validation

YAML by itself is schemaless, and won't complain if you type preqrequisites instead of prerequisites. The rules for what each entry type requires are complicated enough that I can't keep them in my head. Items need an item_slot, equipment needs prerequisites on top of that, gathering nodes need a drop_table, crafting recipes need materials and produces. I made mistakes often enough to build a schema and linter.

Every entry.yml is validated against a layered JSON Schema hierarchy. The base schema requires an id, a name, and descriptions:

{
  "required": ["id", "name", "short_description", "long_description"],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-..."
    },
    "name": { "type": "string" },
    "short_description": { "type": "string" },
    "long_description": { "type": "string" }
  }
}

Each category adds its own requirements. Items need an item_slot, and gathering nodes need both a drop_table and prerequisites. Starting at each entry.yml, the validator walks up the directory tree, collects every schema.json it encounters, and merges them with allOf.

static-db/database/
├── schema.json                  ← id, name, short/long_description
├── items/
│   ├── schema.json              ← item_slot, common_stats, max_stack
│   └── equipment/weapons/swords/iron/entry.yml
└── nodes/
    └── trees/
        ├── schema.json          ← inspect_description, drop_table
        └── oak/entry.yml

The tree schema extends the base with fields specific to trees:

{
  "allOf": [
    { "$ref": "../../schema.json" },
    {
      "required": ["inspect_description", "prerequisites", "drop_table"],
      "properties": {
        "prerequisites": {
          "required": ["woodcutting_level"],
          "properties": {
            "woodcutting_level": { "type": "integer", "minimum": 1 }
          },
          "additionalProperties": false
        },
        "drop_table": {
          "$ref": "../../_schemas/drop-table.schema.json"
        }
      }
    }
  ],
  "additionalProperties": false
}

The additionalProperties: false at the end catches typos. If I write item_slo instead of item_slot, the schema rejects it.

The linter catching a typo in item_slot.

The linter verifies that every @reference points to a real entry.yml.

The linter catching a broken reference.

The linter also enforces formatting and line length. It runs on save in my editor and again in CI. I find mistakes there instead of waiting for something to break at runtime.

The Wiki

It feels a little strange to ship a public wiki before the game is available to anyone other than me.

The wiki reads the same YAML as the server and client, then renders a page for every item, skill, node, and station. Its purpose right now is selfish: it helps me keep things organized.

The game already has a few hundred entries, and that number keeps growing. When I'm working on combat and need to remember the stats on an Iron Sword, the level required to mine iron, or which recipes use Bronze Ingot, I don't want to dig through YAML files. I keep the wiki open while I work. It's faster than grep, and a page with icons, stat tables, and cross-references is much easier to scan than a wall of YAML.

It has also been useful when working with artists. Instead of passing around spreadsheets of item names and tiers, I give them access to the wiki. They can browse the icons and descriptions, and see how the items relate to each other.

How Items Link Together

The wiki turns @ references into clickable links with icons and names. At build time it also scans the full database and computes reverse lookups for every entry:

• "Referenced By" lists entries that mention it in their description
• "Material For" lists crafting recipes that use it as an input
• "Item Sources" lists nodes that drop it and recipes that produce it

None of this is stored. When I add a smithing recipe that consumes Iron Ingot, the Iron Ingot page picks it up under "Material For" without another edit. Recipe pages show the same graph from the other side: materials in, produces out, with chance and quantity ranges on node drops.

This is easier to show than to describe. Here is a Wheat Sheaf, which both has item sources and is a material for other recipes:

I don't have to keep the full crafting graph in my head. The wiki helps me traverse it.

URLs as IDs

The Iron Sword wiki URL is /wiki/items/equipment/weapons/swords/iron, which mirrors its static-db path: items/equipment/weapons/swords/iron/entry.yml. When the server syncs the item into PostgreSQL, it derives the slug from that same path: equipment/weapons/swords/iron.

It's the same path in four contexts:

When the server needs to tell the client "you just received an Iron Sword," it sends the slug. The client uses it to look up the compiled resource for the icon and name. If I ever want to link to the wiki from the game, the URL is already there.

The directory path was a deliberate choice. One path that works as a database slug, a client resource lookup, a wiki URL, and a YAML reference, with no mapping table between them.

The indie game development community has told me this is inadvisable.

Late 2024

In late 2024 I took a few-month sabbatical from work because I was burnt out. I spent the time on creative pursuits, to get away from thinking about computers, and it mostly worked; most of those months went to photography, writing, and sewing. My brain kept floating back anyway, to the same thought exercise: how would I go about designing a multiplayer game server?

I spent a few days building a small proof-of-concept. It came easily; this is what I've done professionally my whole career, and I understood what needed to get done and how to do it. It felt like a beautiful union between my adult domain (software engineering) and my childhood one (gaming, mostly online RPGs).

The client was new territory, and it's been a fun one. I'm trying to build the thinnest client I can, while the server stays in the driver's seat.

Two Years In

I'm coming up on two years of working on this consistently, and a world is starting to emerge from it.

I've recently hit the "this is starting to look like an actual game" phase, instead of it just feeling like a tech demo. It's a little odd to step back, look at it, and buy into the illusion.

It feels like the right moment to start talking about it.

The game side has come a long way too. Players sign in, make a character, and share a world that streams in around them. Many of the gathering and crafting skills are finished, and a real combat system is taking shape.

There's still an extremely large amount of work remaining. The people who called this inadvisable weren't wrong about that part. Luckily, the process is where the joy is for me, and I'm not itchy to reach the end. The goal isn't to finish, it's to do the work. I expect that eventually adds up to a "finished" game.

What the Game Will Feel Like

I played too much Runescape as a kid. What stayed with me was how deep the skilling and crafting went. Professions weren't just a side activity. You could pour hours into them without touching combat or questing, which is mostly how I played. I want that kind of depth.

World of Warcraft was the first game where the world itself felt like the main character instead of me. I think that matters in an online game. You should feel like you're part of something larger, not like everything revolves around you. Everyone else logged in is on a journey of their own, and the world can't be built so that each of you is its main character.

The combat system in Tibia was more creative than its constraints should have allowed: 2D, grid-locked, real-time, and still deep. You had to think about positioning, kiting, and using terrain to your advantage. Grid-locked movement doesn't have to mean simple gameplay.

I'm still pulling from new inspirations as I build, even ones I find long after I started. The gathering system in the Fantasy Life series feels super engaging; I only discovered that series once this project was already underway.

I'm not trying to clone any of them; what I want is the feeling they gave me. If I turn out to be twice as good as I think I am, I might manage half of it.

The game should be slow-paced and relaxing, not stressful or demanding. The kind of game you play while half-watching a show, or sink hours into when you're in the mood.

Progression still has to feel rewarding; there's a line between chill and boring that I'm trying to find. The focus will be PvE. Other players in the world should feel like they're on your team, not your competition. I might add PvP eventually, but that's not the initial focus.

Go and Godot

The server is Go, with no external libraries. The client is Godot, also with no external libraries.

The server is the source of truth. The client shows state in real-time with optimistic updates, and rolls back to server state when it needs to. It's a simple model, and it's worked well so far.

The world is 2D and grid-locked, like Runescape and Tibia, but unlike a lot of grid-based games it isn't tick-based. It's real-time, and every entity has its own thread and can act independently. That decision has enabled some cool things I'll get into in future posts.

I skipped the libraries because I wanted to understand everything from the ground up. It's been a great way to learn, and it's enabled some important performance optimizations. From initial load testing, the server can support hundreds of thousands of simultaneous entities.

What I'll Be Writing About

A lot of it will be technical: architecture decisions, the problems I've run into, and what I've learned along the way. Plenty of it won't be. I'll write about game design too, how I'm thinking about the systems, what I want the game to feel like, and why I've made the calls I've made. I'm writing for other software engineers and game developers who are curious about how something like this gets built.

None of this is a game announcement. The game is far from ready for players, and I'm not willing to make any commitments about when, or if, it ever will be. This is a side project, and the fun is in the building. So there won't be release dates or feature roadmaps here, just the work as it happens.

On Solo Dev

I mostly work on this alone, but there's no such thing as truly solo development. I've commissioned artists for work I couldn't do myself, built parts of it alongside friends, and had enough in-person conversations about the game that there are pieces of it I couldn't trace back to any one person or conversation anymore.

I'm going to do my best to share it as I go.