Arcadia ADL Introduction

This document introduces the Arcadia asset definition language, Arcadia ADL for short, the format in which the assets of Michael Heilmann's Arcadia are stored. ADL is defined by the Arcadia.ADL module: the module reads ADL assets, checks them against their schemata, and builds definitions that the Arcadia engine can consume.

What an ADL asset is

An ADL asset is a text file in the Arcadia Data Definition Language (Arcadia DDL). In the common case the file contains a single map that describes one definition. Every ADL definition carries at least two map entries:

• type, a string that selects the kind of definition and the reader that processes it, and
• name, a string that names the definition. Names are fully-qualified, dot-separated, and unique within an application, for example Colors.Red or MainMenuScene.TextureColorModel.

The remaining entries are specific to the type. For example, the definition below describes the color red:

{
  type : "Color",
  name : "Colors.Red",
  red : 255,
  green : 0,
  blue : 0,
}
      

Many definitions refer to other definitions. References are written as strings that name the referenced definition and are resolved only after all assets have been read. The following definitions, typical for a textured model, form a small example of this:

{
  type : "PixelBuffer",
  name : "Assets.DefaultWall.PixelBuffer",
  width : 256,
  height : 256,
  operations : [ "Assets.DefaultWall.PixelBuffer.FillOperation" ],
}
{
  type : "PixelBufferOperations.CheckerboardFillOperation",
  name : "Assets.DefaultWall.PixelBuffer.FillOperation",
  checkerWidth : 32,
  checkerHeight : 32,
  firstCheckerColor : "Assets.DefaultWall.PixelBuffer.FillOperation.FirstColor",
  secondCheckerColor : "Assets.DefaultWall.PixelBuffer.FillOperation.SecondColor",
}
{
  type : "Texture",
  name : "Assets.DefaultWall.Texture",
  pixelBuffer : "Assets.DefaultWall.PixelBuffer",
}
      

The two phases of loading

Loading ADL assets happens in two phases. In the first phase the application reads the assets into definitions; references between definitions are still unresolved at this point. In the second phase the application links the definitions, which resolves every reference and checks that the referenced definition has the required type.

The example below reads the assets of the previous section from strings, links them, and fetches the texture definition:

Arcadia_ADL_Context* context = Arcadia_ADL_Context_getOrCreate(thread);
Arcadia_ADL_Definitions* definitions = Arcadia_ADL_Definitions_create(thread);
// ... read each asset ...
Arcadia_ADL_Context_readFromString(thread, context, definitions,
  Arcadia_String_createFromCxxString(thread, textureAsset), Arcadia_BooleanValue_False);
Arcadia_ADL_Definitions_link(thread, definitions);
Arcadia_ADL_TextureDefinition* definition =
  (Arcadia_ADL_TextureDefinition*)Arcadia_ADL_Definitions_getDefinitionOrNull(
    thread, definitions, "Assets.DefaultWall.Texture");
      

What else is in this documentation

• The Concepts and Terms document explains the ideas behind ADL: definitions, readers, schemata, references, and linking.
• The Module Interface document is the reference of the public interface of the Arcadia.ADL module.
• The Specification document describes the ADL asset format in detail.