Ember Entity Creator

From WorldForgeWiki

This page contains development documentation on GSoC-2008 project Entity Creator. Coding happens in a branch in separate git repository.

Process of creating entity:

1. Parser is parsing specifications using standard Atlas methods.
2. Lua script for each placeholder is called with values from GUI adapters. Result is transformed into XML structure and replace placeholder.
3. Data is transferred to server to create entity.

Contents 1 Entity recipe 2 Semi-Atlas entity specification 3 GUI adapters description 4 GUI adapters bindings 5 Lua scripts 6 Example

Entity recipe

All information that entity creator uses to create entity is gathered together in one entity recipe file (*.entityrecipe). It has following structure:

<entityrecipes>
  <entityrecipe name="test">
    <entity>
      ... Entity Specification in Atlas-XML format ...
    </entity>
    <adapters>
      ... Description of GUI adapters ...
    </adapters>
    <bindings>
      ... Bindings between scripts and GUI adapters ...
    </bindings>
    <script><![CDATA[
      ... Lua script ...
    ]]></script>
  </entityrecipe>
</entityrecipes>

Semi-Atlas entity specification

It is the atlas-xml structure that have placeholders like $val. DTD is described in documentation.

Attribute type specifies Eris type of entity.

Placeholder should be the only child in element. That is, it should be like <float name="foo">$val</float>. This element will be replaced with resulting value from GUI adapter. Attribute name is maps will be preserved.

<entity type="foobar">
  <atlas>
    <map>
      <int name="foo">13</int>
      <float name="meep">1.5</float>
      <string name="bar">$val</string>
      <list name="args">
        <int>1</int>
        <int>2</int>
        <float>3.0</float>
      </list>
    </map>
  </atlas>
</entity>

GUI adapters description

This part of recipe describe properties of GUI adapters.

<adapters>
  <adapter name="value_of_a" type="list">
    <item value="1">A is big</item>
    <item value="2">A is small</item>
  </adapter>
  <adapter name="value_of_b" type="number">
    <min>10</min>
    <max>100</max>
  </adapter>
  <adapter name="value_of_c" type="color" />
</adapters>

GUI adapters bindings

This part of recipe describe bindings of GUI adapters to correspondent placeholders.

<bindings>
  <bind name="foo" func="calc_foo">
    <adapter name="value_of_a" />
  </bind>
  <bind name="meep" func="calc_meep">
    <adapter name="value_of_b" />
    <adapter name="value_of_c" />
  </bind>
  <bind name="bar" func="calc_bar">
    <adapter name="value_of_a" />
    <adapter name="value_of_c" />
  </bind>
</bindings>

Lua scripts

<script><![CDATA[
  function fTest ()
    print("Yay!")
    return Atlas.Message.Element(123)
  end
]]></script>

Example

Complete example of entity recipe file.

<entityrecipes>
  <entityrecipe name="test">
    <entity>
      <atlas>
        <map>
          <int name="foo">13</int>
          <float name="meep">1.5</float>
          <string name="bar">hello</string>
          <list name="args">
            <int>1</int>
            <int>2</int>
            <float>3.0</float>
          </list>
        </map>
      </atlas>
    </entity>
    <bindings>
      ... Bindings between scripts and GUI adapters ...
    </bindings>
    <script><![CDATA[
      ... Lua script ...
    ]]></script>
  </entityrecipe>
</entityrecipes>