CastleDB: An External Database


May 14, 2012
Reaction score
First Language
Primarily Uses
CastleDB: An External Database

Castle DB Website | Demo (Requires: Node.js, MV 1.6.1)
CastleDB is a lightweight dabatase specifically created for games, which stores its data in JSON. Anything that can be stored in JSON can be stored via CastleDB.

It's open source, free to download and free to use in commercial projects. It's developed by Nicolas Cannasse and used to create games like Evoland.

Why Would I Want It?
One of the main advantages of using CastleDB is that it provides its own simple front-end for editing JSON files. It also provides its own input validation, which allows you to avoid mistakes that can be easily made when you edit JSON files by hand.

In most cases, it will prevent you from entering invalid values in your JSON file, and when it can't prevent it, it will warn you that you've made a mistake.

You can use CDB to edit your own custom plugin JSON files or to add additional information to the existing MV game objects.

This can be incredibly convenient if you have a game with complex objects that can't properly be represented in MV's default database (for example: you're making a D&D RPG and you need a way to edit complex stats). It's also very useful if you have a complicated plugin that requires its own JSON configuration files (for example: Lecode's TBS).

CDB is a good way of providing a graphical inteface to edit all of those things, instead of resorting to large amounts of notetags (which can quickly get unmanageable if you have a complex game), or editing JSON by hand, which is prone to error.

How Does It Work?
Everything in CastleDB is stored in something called a Sheet. If you've worked with dabatases before, you can think of it as a table.

Every Sheet has several Columns, which have multiple Lines. When you create a Column, you assign it a type, which will determine what kind of data it can represent.

Starting out, the most useful column types will probably be the more basic ones - Text, Boolean, Integer and List. As you use CastleDB more, you can find interesting uses for the other types.

The Tile type, for example, can be used to select a part of an image. So if you load a spritesheet - let's say, your game's Iconsheet, for example - you can pick out an individual part of the sheet and assign it to a Column:

In addition, you can also set a Column as Required (right-click on the Column and select 'Edit...'). This will force every element in that Column to always have a value, which can be useful for things like names and icons, which you want to guarantee is never null.

There are two more useful properties to be aware of in CastleDB: Indices and Unique Identifiers.

An Index is just the numerical ID of each line. You can see it on the left side of above screenshot. By default, CastleDB doesn't actually write the line index in the JSON file, so if you want it (you usually do!), you can get it by right-clicking on the Sheet and selecting 'Add Index':

A Unique Identifier is a special Column type that uniquely identifies elements in that Column. It's always stored as text. In the above screenshot, I have the 'key' Column set as the Unique Identifier for Armors. This is used so that you can reference Lines in a Sheet from other Sheets, using the Reference Column type.

Above, the 'description' Column is an example of this. It's not text - it's actually a reference to a Line in the Text Sheet. In the demo example, this allows me to have all of the description text for items in a single sheet. It also allows you to pick its value from a drop-down instead of typing it manually, since CastleDB knows what's in all the other sheets:

As you can imagine, this could also come in handy if you ever decide you want to translate your game. All you'd have to do is have a separate CDB file with all the text in a different language and load that.

There's a lot more you can do with CastleDB, but that covers the very basics. If you want to know more, you can see a more detailed explanation of all of the available Column types in the CastleDB website.

How Do I Use It?
When you use CastleDB, it creates a '.cdb' file. This is where it stores everything you see in the editor. It's called a '.cdb', but it's actually just a JSON file, and you can open it in any text editor. If you open the CDB in the demo project, you'll see something like this:

That means you can load it in RPG Maker using

...and that's pretty much all you have to do to load the CDB data into your game. You can see its formatting and contents by printing it out to the console:

Then, all you need to do is take the data that's in there and put it wherever you need it to be in your game. See the plugin included in the demo for a more detailed example of how to do this.

Example Usage
You can use CastleDB to do a number of things. Download the demo to see a few examples of this in practice.

In the demo, I cover three separate example cases:

1. Extending MV's Sound Effect Database
MV has this pretty convenient box in the System tab that lets you define sound effects for a bunch of common triggers, like the cursor sound, or the sound when you load a game. But you can't add to this. What if you need more? Like, for example, what if your game UI also has buttons and checkboxes and radio buttons and you'd like to define sound effects for them too?

Normally, you'd have to write this directly into a plugin, and you wouldn't really have any easy way of modifying what sound effect plays when something happens. The best you could really do is pass it as a plugin parameter. That's fine if you only have one or two, but if you have a bunch and you're adding and modifying them all the time, it can get a little tedious.

What you can do instead is have a Sheet on CastleDB that lists your unique sound effect types and what files they play, then play those from your plugin.

2. Using CDB As A Text Database

I've already touched on it above, but it can be really useful to separate the text in your game from everything else. This not only makes it easier to translate, but it's also easier to look over and catch typos and spelling or grammar mistakes. You can use CastleDB to put all of it in one place and edit it all together, in a spreadsheet format where it's easy to read. Since the exported '.cdb' file is still plain JSON, you can also use it with any translation helper tool made for use with RPG Maker MV games.

In the included demo, the descriptions of all the armors are written in CastleDB. You can easily edit them by changing the contents of the Text Sheet and reloading the game to see the results, without having to dig into the RPG Maker MV menus, or even closing the game window. It might seem like a simple change, but it makes editing text feel much quicker and easier.

3. Using CDB To Edit Armors

Since anything you write in CastleDB is exported to JSON and all of MV's data files are also JSON, you can use CastleDB to edit anything in MV's database instead of actually using MV's default database editor. In the demo, I show an example of how to do this for Armors.

Most of the basic parameters are included (I've excluded traits for brevity, but you could easily add those too), but I've also added my own custom parameter to armors: Weight. It's a new stat that doesn't exist in MV items. I do this by creating a separate Params Sheet, then referencing it in the armors Params Column, which contains a list of Param references, and values for each Param. The included plugin then has some additional code to read those in-game, and store them in a format RPG Maker recognizes, which is done when the game loads.

Try running the demo, putting on different equipment and talking to the NPC on the left side of the map to see a simple way this can be used.

In this example I'm only adding one parameter for the sake of simplicity, but you can see how, after you've set up something like this, you can add any number of additional parameters to your game just using the CastleDB tables, without ever having to write any additional plugin code.

This is what my Param table looks like in the game I'm currently working on:

Between stats, skills, resistances and a bunch of other things, there's about 70 parameters in there. Every time I need a new one, it takes about 30 seconds to add a new line in the Params sheet, and reload my game.

There are a bunch of other things you can do with CatleDB that I haven't covered. It even has its own map editor which has support for auto-tiles and as many layers as you want. It's not as in-depth as something like TileD, but it's another interesting thing CDB can do that's worth exploring if that sounds like something you might want.

If you want additional info, there's also a CastleDB video tutorial that gives a visual explanation on how it works:

I've been using this for a little while now for my own game and it's saved me an enormous amount of time on database editing.

It's not plug-and-play - you do have to write a plugin for your own game to read in the CDB files and load them in RPG Maker in whatever format you need to use them - but once you set it up, it makes anything database-related significantly easier and more convenient.

Hopefully the information above helps out. I think it would be very useful to anyone creating a more complex RPG than what MV supports out-of-the-box, and also to plugin developers making large, complex plugins which have JSON configuration files.

Feel free to ask any questions!
Last edited:


Level 99 Demi-fiend
Mar 1, 2012
Reaction score
First Language
Primarily Uses
I've been looking forward to this. Can't wait to try out the demo. So far it seems really easy to use!


May 14, 2012
Reaction score
First Language
Primarily Uses
Some additional information on using CDB. This is a quick demo of how CDB works done by the creator himself at Haxe Summit 2017:

He shows how they used CDB to make Northgard, and pulls up the game's real database files for demonstration. The talk covers all the different tools they used; for the CDB-specific parts see 1:21:12 to 1:37:45.

Users Who Are Viewing This Thread (Users: 0, Guests: 1)

Latest Threads

Latest Posts

Latest Profile Posts

Got any suggestions?

Here is my valiant and beloved captain
of the space cruiser ROSTOV.
Made a video showcasing a plugin (by Triacontane) that allows us to summon a relative touchpad/analog stick wherever we touch on the game's screen. (Mostly for mobile RPG Maker games.)

EmptyVoid_ wrote on Leporine's profile.
Just letting you know that I have written a PM to you.
Testing testing. First time doing this.

What are we, facekook?

Forum statistics

Latest member