Create account / Log in

Design of property and piece XML for V4

Discussion area for the development team.

Moderators: uckelman, Tim M

Design of property and piece XML for V4

Postby uckelman » September 9th, 2012, 9:18 pm

Ainulindale and I have recently been discussing in the IRC channel what we might do for representing piece and property data in V4. I'd like to present some of it here, in order to get comments and criticism. Please give this a read through and consider whether it covers the kinds of cases you're likely to encounter in module construction.

First, a few notes:

1. I'm purposely omitting anything to do with piece behavior, and being vague about how piece faces are connected to images in order to let us focus on one part of the problem, namely representing piece properties.

2. I'm presenting elements in dependency order, so that in each example, all elements other than the one being defined have already been defined themselves. The structure will become clearer as you go.

3. I'm not intending for the average module designer to look at the XML; for those users, it's important that the XML support the kind of structure we want to expose in the module editor. But there will be users who want to manipulate the XML directly or with scripts, or will need to look at it for troubleshooting purposes, and for those users I want the XML to be readable, while still making complex things possible.

4. What's below is derived from what Ainulindale came up with two weeks ago, but he hasn't seen my proposed templating system, so don't assume he's endorsing it. :)

Now for the proposal:

Enumerations:
Code: Select all
  <enum id="direction">
    <item>north</item>
    <item>south</item>
    <item>east</item>
    <item>west</item>
  </enum>

An enum element has an id which names it, and contains zero or more item elements which indicate the values contained in the enumeration. (If you're familiar with C, C++, or Java, this is intended to have the same meaning as enums in those languages.) The purpose of an enum is to define a type with a limited range of values.

Properties:
Code: Select all
  <stringProperty id="name" value="101 Airborne"/>
  <intProperty id="movement" value="4"/>
  <floatProperty id="angle" value="60.0"/>
  <enumProperty id="direction" value="north"/>

Each property element has an id attribute which names the property and a value attribute which provides the value of the property. The type of the value is encoded in the name of the property element. E.g., intProperty is intended for holding integers, stringProperty for holding strings, and so on. The permissible range of values for an enumProperty is the same as the items in the enum named by the enumProperty's id attribute. (Question: Would it make more sense to have an "enum" attribute for enumProperty, so that the enum referred to need not have the same name as the enumProperty?) This isn't intended to be an exhaustive list of property elements. (Question: What other types might we want? E.g., other numeric types---such as bool, or unsigned types, or maybe numeric types range-limited in other ways---or dates, or a refProperty which takes an id reference as a value.)

Faces:
Code: Select all
  <face img="101 Abn front">
    ... properties ...
  </face>

A face element has an img attribute which refers to the image to be used for that face. Face elements may contain any number of property elements as children.

Pieces:
Code: Select all
  <piece id="101 Airborne">
    <intProperty id="movement" value="4"/>
    ...
    <face img="">
      ...
    </face>
    ...
  </piece>

A piece may have any number of properties and any number of faces.

Templates:

Now for something abstract. A template establishes a pattern to be reused elsewhere. Here's an example:
Code: Select all
  <template id="infantry">
    <body>
      <enumProperty id="type" value="infantry"/>
      <intProperty id="movement allowance" value="4"/>
    </body>
  </template>

  <piece id="10/1/1">
    <use template="infantry"/>
  </piece>

The template element establishes a named block of XML which can be inserted elsewhere by reference. The use element indicates the location where the body of template it refers to should be inserted. Effectively, the above is equivalent to:
Code: Select all
  <piece id="10/1/1">
    <enumProperty id="type" value="infantry"/>
    <intProperty id="movement allowance" value="4"/>
  </piece>

Old hands will recognize this as a V3 piece prototype. The templates I'm proposing here generalize prototypes somewhat, by accepting named parameters:
Code: Select all
  <template id="infantry">
    <parameter id="MOVE"/>
    <body>
      <enumProperty id="type" value="infantry"/>
      <intProperty id="movement allowance" value="{MOVE}"/>
    </body>
  </template>

  <piece id="10/1/1">
    <use template="infantry">
      <parameter id="MOVE" value="4"/>
    </use>
  </piece>

I've added three things here: First, there is a parameter element in the template. The intent of this is to signal that the template expects to be called with a parameter named "MOVE". Second, the use element now has a parameter element as a child with "MOVE" as its id (to match the parameter name in the template) and "4" as its value. Third, if you look into the template body, you can see "{MOVE}" as the value of the "movement allowance" property. This signals where the value of MOVE will be inserted when the template is expanded. This second template example is intended to define a piece equivalent to the one which the first example does.

Furthermore, it might be convenient for templates to specify default values for their parameters, like so:
Code: Select all
  <template id="infantry">
    <parameter id="MOVE" default="4"/>
    <body>
      <enumProperty id="type" value="infantry"/>
      <intProperty id="movement allowance" value="{MOVE}"/>
    </body>
  </template>

This way, if the "infantry" template is used without a value for MOVE, MOVE will default to "4".

More complex things are possible: A template may have multiple parameters. More than one parameter may be substituted into an attribute value (e.g., name="{OWNER} {SIZE} {TYPE}"). Templates may be nested. This:
Code: Select all
  <template id="foo">
    <parameter id="X"/>
    <body>
      <intProperty id="x" value="{X}"/>
    </body>
  </template>

  <template id="bar">
    <parameter id="Y"/>
    <body>
      <use template="foo">
        <parameter id="X" value="{Y}"/>
      </use>
    </body>   
  </template>

  <use template="bar">
    <parameter id="Y" value="1"/>
  </use>

is equivalent to this:
Code: Select all
  <intProperty id="x" value="1"/>

I'm not recommending that you write a simple property in such a complex way; rather this is an example showing one way one might compose templates.

The scope of template parameters is the entirety of body of the template where they are defined. Template parameter values are not inherited by templates used within other templates. If you're familiar with C++ templates, you might be thinking this looks rather familiar. You'd be right, as I modeled this on C++ templates. (NB: The body element in templates could be dispensed with. I don't see an obvious need for it right now.)

So, some questions:

Does this look sufficiently powerful to capture what we want to represent for pieces?

For those of you who might work with this by hand or with scripts, does this look like something you'd want to use?

Can you think of improvements to the syntax?

I've attached an example using the pieces from the game Battle for Moscow, to give you a sense of how this might look in practice.
Attachments
bfm.zip
XML for Battle for Moscow pieces
(1007 Bytes) Downloaded 252 times
User avatar
uckelman
Site Admin
 
Posts: 8848
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Re: Design of property and piece XML for V4

Postby Ainulindale » September 10th, 2012, 10:55 am

On Sun, Sep 9, 2012 at 11:18 PM, uckelman wrote:

>
> 4. What's below is derived from what Ainulindale came up with two weeks
> ago, but he hasn't seen my proposed templating system, so don't assume
> he's endorsing it. :)
>

Likeable disclaimer :-)


>
>
>
>
> (Question: Would it make more sense to have an "enum"
> attribute for enumProperty, so that the enum referred to need not have
> the same name as the enumProperty?)


As I told you before, your use of the key of an enum as the id for the
instantiation of that enum seems to be a syntaxic abuse to me.
Plus, if we picture a piece such as a tank which will have a "direction"
it's going to, as well as a direction he's pointing to (being able to
rotate its guns), then we'd have two directions.
So in this specific case, I'd instantiate the property and define its type,
eg:

This isn't intended to be an
> exhaustive list of property elements. (Question: What other types might
> we want? E.g., other numeric types---such as bool, or unsigned types, or
> maybe numeric types range-limited in other ways---or dates, or a
> refProperty which takes an id reference as a value.)
>


I think we'll pretty much have to implement simple types such as int,
float, date, string, bool. After that we should apply constraints on the
elements.

For example let's take my point about tanks and assume that the direction
of the guns is between 1 and 6, and due to the rotation, wraps at 1 when
going beyond 6:

wrap="true" />

This emulates pretty much the numeric dynamic property, and I think this
has some value.
Obviously we should come up with a syntax which will be transversal to
types (so maybe as child elements).

Templates:
>
> Now for something abstract. A template establishes a pattern to be
> reused elsewhere. Here's an example:
>
>

What annoys me in your "template model" is that it is confusing if used in
the wrong way (as designers will obviously do).
Sure, we need to be able to refer to "rules" or behaviors from one piece to
another, that's agreed upon. But we also need to define types of objects
which will be of the same nature, that is, for C++/Java/OO guys,
inheritance. Maybe they're technically the same, but your way to explain
templates does not imply as much as I would like it to.

So for instance, let's say I have unit pieces which will always have a
specific property for their hit points, as well as a specific face for when
they're dead. I'd say:















So, to me, all major objects types should be templatable, doing a clear
distinction between an object type (face, piece, map) and a template (a
repeatable portion of XML). The former being of the same nature (one can
say "all units"), and the latter allowing concision in the code for
different pieces having the same behavior.
The next question is, should we treat such types as object inheritance or
interfaces, object-oriented wise? The latter may be more flexible IMHO.

So, some questions:
>
> Does this look sufficiently powerful to capture what we want to
> represent for pieces?


It's yet to be less verbose in my opinion (see above).


>
> For those of you who might work with this by hand or with scripts, does
> this look like something you'd want to use?
>

Obviously yes, although it lacks // and ;;

Can you think of improvements to the syntax?
>

A lot but there's not enough room in the margin :-)

--
Julien Cassignol
http://www.ainulindale.net
Ainulindale
 
Posts: 29
Joined: July 12th, 2012, 8:17 pm

Re: Design of property and piece XML for V4

Postby Ainulindale » September 10th, 2012, 12:12 pm

Uckelman asked me to clarify. Here's the (hopefully effective)
clarification. Beware, it's long.

First, please consider that I'm more inclined towards types because I think
that this enforces a way to design which I deem more desirable. It forces
the designer to structure its objects in terms of a hierarchical tree in
which objects have shared properties.
A good example is the units, we'll have something such as :

UNIT
/ \
INFANTRY VEHICLE
/ \
TANK BIKE

Translated: a bike is a vehicle, but also an unit. An infantry isn't a
vehicle but is a unit. A tank is a vehicle but is not a bike.
Your typical object model.
The fact that one is strictly forced to model its thoughts using that kind
of thought process is of value, to me, in terms of what we allow and what
we will have to debug.

In terms of functionnality, Uckelman's concepts as well as mine are, I
think, the same with more or less verbosity depending on the situation. I
just think that his is too much permissive or doesn't give enough
information to the engine.
That's why I think that having a type hierarchy in the XML, with "abstract"
objects extended by implementing objects, is easier.

In the following examples, I assume that parameters are transferrable
through hierarchy of template or type uses, as well as the usability of
"id" as a parameter.

Here's an example. Consider 4 decks of cards, each with one color from 1 to
K:

Both solutions will share this:



...



----------------------------------
My proposal:
----------------------------------
















...





















----------------------------------
Uckelman's proposal:
----------------------------------































Another example illustrating what I wrote before for units:

----------------------------------
My proposal:
----------------------------------













































----------------------------------
Uckelman's proposal:
----------------------------------