Registries

From OrbEdit Wiki

Registry Basics

Data organization is an important task when making a game. Most games need a lot of data, things such as character attributes, weapon attack rates, enemy statistics, and dialog trees. This data needs to be easy to define, store, and modify.

Orb uses a set of special Lua classes called Registries for these purposes. A Registry is really nothing more than a thin wrapper around a Lua table. Just like Lua tables, Registries act as associative arrays, that is, each object stored within a Registry is associated with a key. You can later retrieve an object with the key that it was stored with. Think of a Registry as a lookup table for some part of your game; whenever a player casts a spell, for example, you can retrieve that spell's data from your SpellRegistry, in order to calculate its damage, display its graphic, and play its sound effect. Orb uses several Registries for its own data organization; the FontRegistry for Fonts, the ShaderRegistry for Shaders, and the DSPRegistry for DSPs.

An Orb Registry has nothing to do with the Windows registry. Unless you count the fact that they had a brief fling together in high school :)

Registries have the following methods:

• Registry:put(key, object): Stores the object object under the key key in the Registry.
• Registry:get(key): Gets the object stored under key key.
• Registry:has(key): Returns a value indicating whether or not the Registry has an object stored under the key key.
• Registry:load(): Loads the Registry.

The thing that makes a Registry special is not how it stores its data, but how it loads its data. All Orb registries get their data from an XML file, known as a registry file. For example, the ShaderRegistry, which stores all of Orb's Shaders, gets its data from the registry file /Shaders/shader_registry.xml. When a Registry is loaded, it runs an XSL transform against its registry file, which converts it into a Lua file. That Lua file is then executed and loads individual objects into the Registry. Science!

XSL

So what the heck is an XSL transform? XSL is a language that allows you to parse through XML data and transform it into another format, such as Lua. XSL has functions, variables, and control statements just like any programming language. Orb makes extensive use of XSL for turning XML into Lua. You can check out some example XSL transforms in the /XSL directory. The naming convention for these XSL files is gen_target.xsl, where gen stands for "generate" and target is whatever you're generating. For example, /XSL/gen_shaders.xsl generates Shaders.

Writing your own XSL transform can be a tricky thing and is covered in more detail in Custom Registries. For general Registry loading, Orb provides a default transform, /XSL/gen_default.xsl, which you can use to load a basic Registry.

Item Example

<!-- Items.xml -->
<ItemRegistry DataElement="Item">  <!-- The DataElement attribute specifies the elements within that contain actual data -->
  <Consumables>
    <Item Name="LifePotion" Description="Cherry flavored, heals 50 HP" HP="50" Target="Player" Icon="Images/Items/LifePotion.png"/>
  </Consumables>
 
  <Weapons>
    <Item Name="Longsword" Description="The staple of knights everywhere" AP="100" Icon="Images/Items/Longsword.png"/>
    <Item Name="Crossbow" Description="A technological masterpiece" AP="80" Icon="Images/Items/Crossbow.png"/>
  </Weapons>
 
  <Armor>
    <Item Name="Buckler" Description="A small shield, but better than nothing" AC="20" Icon="Images/Items/Buckler.png"/>
  </Armor>
</ItemRegistry>

This would become registry file for your ItemRegistry class:

---- Registries.lua
---- class: ItemRegistry
ItemRegistry = Registry:new({});  -- All Registries must inherit from the base Registry class
 
-- Run the default XSL transform to populate this Registry
function ItemRegistry:load()
  print("Loading Item Registry...");
  orb.runXSL("Scripts/Registries/Items.xml", "/XSL/gen_default.xsl");
end

When the ItemRegistry loads, it will run the default transform, /XSL/gen_default.xsl, against the registry file, Items.xml, resulting in a Lua file that looks like this:

local LifePotion = {};
LifePotion.Name = "LifePotion";
LifePotion.Description = "Cherry flavored, heals 50 HP";
LifePotion.HP = 50;
LifePotion.Target = "Player";
LifePotion.Icon = "Images/Items/LifePotion.png";
ItemRegistry:put("LifePotion", LifePotion);
 
 
local Longsword = {};
Longsword.Name = "Longsword";
Longsword.Description = "The staple of knights everywhere";
Longsword.AP = 100;
Longsword.Icon = "Images/Items/Longsword.png";
ItemRegistry:put("Longsword", Longsword);
.
.
.

This Lua file is then executed and loads up the ItemRegistry. The name of the Registry to load is dictated by the name of the root element in your registry file. The root element must also have an attribute named DataElement, which points to the elements within that actually define data. Note that in the above example, that is the <Item> element; the <Consumeable>, <Weapon>, and <Armor> elements are purely for organization of the file.

This example is continued in Custom Registries

Summary

To sum up the above information:

• Registries are special Lua classes that are designed to hold game data.
• Each Registry has its own registry file; an XML file that defines its data.
• A Registry uses an XSL transform to turn its registry file into a Lua script that will load its data.
• You can (and should!) create your own Registries.
• You can use the default XSL transform (/XSL/gen_default.xsl) to load your Registry, or write your own XSL transform.