CastleDB: structured game data in a JSON file, edited through a local spreadsheet

CastleDB is for static data that designers have to edit

CastleDB is described as a structured database and level editor with a local web app to edit it. The use case the README gives is concrete: CastleDB is used to input structured static data, so everything that is usually stored in XML or JSON files can be stored and modified with CastleDB instead. The example is a game holding all of its items and monsters, with names, descriptions, and logic effects, in CastleDB. The audience is therefore a game development team where the data is authored by designers rather than by programmers, and where that data needs a schema attached to it. The alternative to the tool is a folder of JSON files that only the programmer can safely touch, which is exactly the situation the project is designed to remove.

Each sheet carries a model, which is what turns a table into a schema

CastleDB looks like any spreadsheet editor, except that each sheet has a data model. The README is explicit about why that matters. The model allows the editor to validate data and eases user input, and the example given is a column that references another sheet row, where the editor lets you select the row directly instead of typing an identifier. That is the core idea, and it is the same idea that a relational schema gives you, applied to what is otherwise a flat file. It also means the model is not decoration. The structure that describes the data is stored alongside the data, so the validation a designer gets at edit time and the structure a program reads at load time come from the same source, rather than from a schema documented somewhere else that nobody updates.

Storage is one JSON file, and the data model travels with it

CastleDB stores both its data model and the data contained in the rows into an easily readable JSON file, which it can then easily be loaded and used by any program. This is the design decision with the longest reach, and it is worth being clear about what follows from it. Because the output is a plain JSON file, the consuming side of your project needs no CastleDB runtime to read the data. Any language, any framework, any tool that can parse JSON can consume it, and the data is diffable, reviewable, and mergeable. The cost is that the JSON carries both the rows and the model, so a reader has to understand both to interpret a file, and a hand-edited file can drift from what the editor would produce. The README does not discuss validation of the file outside the editor, so treat the editor as the only supported path for changing the data.

Newlines in the JSON are what make merges work

The collaboration story is the part of CastleDB that is genuinely different from an online spreadsheet, and it hinges on a formatting decision. CastleDB uses the JSON format with newlines to store its data, which in turn allows RCS such as GIT or SVN to diff and merge the data files. Unlike online spreadsheet editors, changes are made locally, which allows local experiments before either committing or reverting. A spreadsheet backend that stores a whole document as one opaque blob gives you a diff that says the file changed, and a merge that has to be resolved by hand every time two people touch the same sheet. A newline-formatted JSON file gives you a line-level diff and, in many cases, a merge that a version control system can apply without a human. The cost of that property is that the file format is not negotiable. If a tool rewrites the JSON without newlines, the merge story collapses, so any tooling you add around the data has to preserve the format.

Building from source is a Haxe toolchain and an NWJS runtime

The README's compilation instructions are the concrete part. You need Haxe, installed with the appropriate installer, and then the dependencies are installed with `haxelib install castle.hxml`, using the hxnodejs project. You clone the repository and, at the root of the repository folder, you run `haxe castle.hxml`, which creates a `castle.js` file in the `bin` folder. To package or run it, you download and copy NWJS from nwjs.io into the `bin/nwjs` directory, then run `cdb.cmd` on Windows or `nwjs/nwjs` from the bin directory on Linux. On OSX you need to copy all bin files into `bin/nwjs.app/Contents/Resources/app.nw` and then open the NWJS application. The packaging story for the three platforms is therefore the same manual procedure, and the NWJS runtime is a dependency you have to supply rather than something bundled. The repository layout matches: `castle.hxml` at the root, the `cdb/` directory, `src/`, `www/` for the editor front end, and `bin/` for the build output.

The editor here is legacy, and the README says so up front

The most important sentence in the README is the important note at the top: the CastleDB editor has been rewritten to be integrated with HIDE, while the Castle library is still being developed but the editor here is legacy. That changes what this repository is for. The library, the part that reads and interprets the structured data, is the thing still under active work, and the editor in this repository is the older generation of the tool. The project dates back to the era of packaged zip downloads, and the download section links to Windows x64, OSX x64, and an NWJS package version 1.5, with the note that to run the package you download nwjs.io and put `package.nw` into the nwjs directory. The only tagged release listed is 1.6.0 from 2018-04-09, while the last push was on 2026-10-14. That gap between the last release and the last commit is the practical signal: the code is being worked on, but the packaged downloads are not the current state of the project.

What CastleDB is not

Several things this project is not are worth naming before anyone adopts it. It is not a database server. There is no query language, no concurrency model, no transactions, and no network service; the editor is a local web app running in NWJS that edits a file on your disk. It is not a runtime store for data that changes while the game runs, since the whole model assumes data is authored ahead of time and then loaded. It is not a hosted collaboration tool with accounts and permissions, because the collaboration model is Git and SVN, not concurrent editing. And it is not a general purpose content management system, since the data model is defined in the editor rather than by an administrator. If any of those sound like what you need, an actual database or a proper asset pipeline is the right direction. If what you need is a JSON file that designers can safely edit and that merges cleanly under version control, then the specific set of constraints above is the feature.

Editorial conclusion

CastleDB fits a game studio that keeps item, monster, quest, or level data in JSON or XML and wants designers to edit it with validation instead of a text editor, especially a team already working under Git or SVN where the diffable JSON matters. It is the wrong tool for a project whose data changes at runtime, since the whole premise is static data loaded from a file, and it is the wrong tool if you need a hosted, multi-user editor with permissions, because the editor runs locally on your machine. Before adopting it, note that the README marks the editor here as legacy in favour of HIDE, so you should decide whether you are taking the library, the editor, or both, and plan on building from source with Haxe rather than expecting a current packaged build.

Frequently asked questions

Official sources

1. Issues
2. License: ISC
3. ncannasse/castle on GitHub
4. README
5. Releases