ASUL Document

ASUL documents are XML files containing GUI definitions for the engine and its plugins. An ASUL document can contain any number of elements, and any number of style definitions.

An element must have an id to be usable in the engine / a plugin. The id is given in the attribute named.

Example:

This box can then be used inside the engine or within plugins.

= Styles = Styles are template definitions of attribute values. The syntax is similar to CSS. Styles can be applied using the  attribute (analog to the   attribute in HTML).

To use it inside an  file, pack the style inside a CDATA tag inside   tag:

Nomenclature

 * Path:,  ,
 * Class: ,
 * Definition:,  ,
 * Attribute:,  ,
 * Value:,  ,

Note: if there is some better suited naming, feel free to correct this. This is just what felt most natural to me.

All definitions made in a class will be used to set the attributes of elements the class' path to. This means that you can use all the attributes you could set directly on an object.

Weight / Overriding
The weight of classes differs, here is the basic order. The further down, the stronger the definition. Meaning that definitions will override all definitions listed above them, but be overridden by definitions below them. If two equally weighted classes exist, the last defined one will be stored.
 * 1) element type, e.g.
 * 2) class, e.g.
 * 3) element bound class, e.g.
 * 4) paths, e.g.   (note that here, again, classes are stronger. I.e. this definition is weaker than  ).
 * The longer the path, the stronger it is. I.e.  is stronger than.
 * A path must be fully matched to be applied.

There can be multiple  blocks in a document, they will be parsed one after the other, but effectively handled like one big block. If a definition is encountered twice, new attribute values are additionally stored, duplicate definitions will result in the later definition to be used (the one further down).

MegaZine3 specific
In the MegaZine3 engine, all style declarations from the  file are made available in each plugin's ASUL definitions, where they can be used or overridden as needed. This allows a more centralized definition of commonly used styles, e.g. for buttons or other components.

= Scripting =

= Elements = Elements are defined in the form of XML nodes, where the root node must have an id to be referenced to in the engine. All elements can be put into any other element. It is left up to the designer to decide what is most efficient and makes the most sense. Some elements define requirements or use for child nodes, sometimes of a special type. Those child nodes will have to be named as defined by the element. As a common convention, those names start and end with a  character. On the example of the ProgressBar:

Two child nodes are used,  for the loading bar graphic, and   to textually display the progress. Either of the two could be omitted, even both of them, though. Furthermore, they could be nested deeper inside other childnodes, e.g.

The engine could then access the progressbar using its id. Note, that usually a plugin defines a set of ids it requires / uses. Setting ids to something never used in the engine is obviously not very useful. The best reference is probably the set of ASUL documents that are released with the default plugins.

Those special child nodes are searched breadth-first.

The actual attributes of the elements, their design and layout, is in most cases irrelevant to the functioning of the engine, allowing the designer a lot of freedom to customize the GUI.