Tuesday, February 5, 2013

Ryzom Core: The Data Is Everywhere!

Ryzom Core has huge amounts of data to facilitate the world and its general running. However the nature of Ryzom Core data often times confuses new users of the platform. Many see the process of create the MySQL database and without fault assume that everything is persisted there. In reality very little data is actually retained in MySQL as the Ryzom Core platform was developed in a time before MySQL could be trusted with the workload live Ryzom required.

 So where is data stored in Ryzom Core? There are a plethora of types and locations. There are a lot of one-off scenarios as well but these are the major players:

  • MySQL for Shard Administration, WebIG apps and user accounting
  • Georges Sheets for static world data.
  • Primitives for world content and layout
  • PDR for persistence.

The MySQL Data Store

The MySQL databases are solely used by the services for general shard administration. This is where the shard services and domains are defined and how AS (Admin Service) knows what should be running and where. MySQL is also typically where any Ryzom API apps will stored their persistent data that isn't directly related to in-game data. For example a 'mailbox' app would store mail in a MySQL database more than likely.

When you sign up for a Ryzom Core account either through a custom signup form or through the user auto-generation that's enabled by default your user account and account privileges are stored in MySQL. This is just basic information like username and password, what shards you have access to and what privileges you have (such as GM or CSR.)

Georges Sheets

To understand what Georges Sheets are you have to understand what Ryzom Core means by "static data" versus world content. While primitives, discussed next, don't contain any persistent information they lay the world out in its base initial form. The Georges Sheets (which are compiled into packed sheets, a more complicated topic but essentially a compressed binary variation of the sheets) contain all of the static data that define things such as fauna, items, spells, and so on. These sheets define the characteristics that make up a mob or NPC but do not actually define a specific mob or NPC. This is the base data that you use to begin laying your world out.

Sheets also contain other static objects such as lists of titles, defining animations and animation sets, continents, starting player characteristics, and more. 

All of these are located in code/ryzom/common/data_leveldesign/leveldesign. You edit these sheets with the Georges Editor tool and they're essentially XML files with a parent/inheritance relationship capability.


While you can go into Georges Editor and create an NPC creature sheet that doesn't put that NPC anywhere on the map. In fact it doesn't necessary describe a specific NPC. Primitives, edited by the World Editor tool, define what the base version of the world, untouched by players, looks like. The layout defined in the primitives is what the world will look like when the shard is first started. 

To illustrate the differences between primitives and sheets when you add a new NPC you provide all of the details regarding that NPC including the ability to change its equipment and color. One of the things you do when defining an NPC is choose the sheet that defines them. This means that you create one NPC creature sheet as a template and then are able to layout actual NPCs with defined characteristics throughout the world.

In Ryzom Core you cannot place a specific mob (fauna) - as mobs and NPCs are distinctly different things. Instead you define what their patterns are and let the AI take over spawning, migration and so on. In the primitive you can configure this behavior but your primitive content will always reference a sheet which defines the basic characteristcs of the fauna as a template.

You can see the pattern now - Georges sheets provide the template, primitives provide the layout and structure and players provide the evolution. But since neither Georges or primitives store the world state that brings us to the next part.

All of these are located in code/ryzom/common/data_leveldesign/primitives. You edit these sheets with the World Editor tool and they're essentially an XML format (called Ligo).

PDR Data Stores

So if MySQL, Georges and Primitives aren't keeping track of characters, equipment, guilds and other such things that persist through shard reboots what is? The Ryzom Core supporting framework, NeL (Nevrax Library) has a rich and sophisticated serialization system. Nearly any object in Ryzom Core can be serialized into a stream to be transmitted over the wire or saved to a file. This means instead of having to translate a character object into MySQL insert/update statements Ryzom Core is able to simple pass the character object to a NeL file object and save it to disk or read it from disk.

The Ryzom Core service infrastructure takes this one step further with the PDR or Persistent Data Record system. This sophisticated system is able to replicate changes to other services in the shard and is maintained to disk through a master/slave backup service. This is the real source of runtime persistence in Ryzom Core. Where the data is stored is in the shards save_shard folder and depends on the type of data.

For example lets use characters. Characters are stored in code/ryzom/server/save_shard/characters in a pattern that the services determine. The actual file names are something like code/ryzom/server/save_shard/characters/001/account_1_0_pdr.bin where the 001 is simply a mechanism the services use to break up accounts into multiple folders (so you don't end up with 100k files in a single folder), the other two numbers (1 and 0) refer to account ID and character slot, respectively.

You can view the contents of the PDR bins using the pdr_util. While not encouraged as this is typically internal Ryzom Core data you can extract a PDR into XML, modify it and then re-assemble it using this tool. This would be helpful if you were, for example, writing a script to mass update characters for some reason.


  1. Nice read and very interesting stuff - thanks for your writeup!

  2. This comment has been removed by a blog administrator.