222Component type instances go through one of two lifecycles:
223
224@code
225CCmpExample();
226Init(paramNode);
227// any sequence of HandleMessage and Serialize and interface methods
228Deinit();
229~CCmpExample();
230@endcode
231
232@code
233CCmpExample();
234Deserialize(paramNode, deserialize);
235// any sequence of HandleMessage and Serialize and interface methods
236Deinit();
237~CCmpExample();
238@endcode
239
240The order of <code>Init</code>/<code>Deserialize</code>/<code>Deinit</code> between entities is mostly undefined,
241so they must not rely on other entities or components already existing; @em except that the @c SYSTEM_ENTITY is
242created before anything else and therefore may be used, and that the components for a single entity will be
243processed in the order determined by TypeList.h.
244
245In a typical component:
246
247- The constructor should do very little, other than perhaps initialising some member variables -
248 usually the default constructor is fine so there's no need to write one.
249- @c Init should parse the @c paramNode (the data from the entity template) and store any needed data in member variables.
250- @c Deserialize should often explicitly call @c Init first (to load the original template data), and then read any instance-specific data from the deserializer.
251- @c Deinit should clean up any resources allocated by @c Init / @c Deserialize.
252- The destructor should clean up any resources allocated by the constructor - usually there's no need to write one.
253
254
255@subsection schema Component XML schemas
256
257The @c paramNode passed to @c Init is constructed from XML entity template definition files.
258Components should define a schema, which is used for several purposes:
259
260- Documentation of the XML structure expected by the component.
261- Automatic error checking that the XML matches the expectation, so the component doesn't have to do error checking itself.
262- (Hopefully at some point in the future) Automatic generation of editing tool UI.
263
264@c GetSchema must return a Relax NG fragment, which will be used to construct a single global schema file.
265(You can run the game with the @c -dumpSchema command-line argument to see the schema. Do not forget to also specify the used mods with @c -mod=<mod>.).
266The <a href="http://relaxng.org/tutorial-20011203.html">official tutorial</a> describes most of the details
267of the RNG language.
268
269In simple cases, you would write something like:
309The <code><data></code> elements are native elements, while the <code><ref></code> elements are elements added for our engine. These non-native elements allow the definition of an operation that depends on the parent template. Possible operations are "add" and "mul", and can be applied as the example below.
310
311Say the parent template is
312@code
313<Entity>
314 <Example>
315 <Name>Semi-Humanoids</Name>
316 <Height>9000</Height>
317 <Eyes/>
318 </Example>
319 <!-- ... other components ... -->
320</Entity>
321@endcode
322and the child template appears like
323@code
324<Entity>
325 <Example>
326 <Name>Barney</Name>
327 <Height op="add">5</Height>
328 <Eyes/>
329 </Example>
330 <!-- ... other components ... -->
331</Entity>
332@endcode
333then Barney would have a height of 9005.
334
335Elements can be wrapped in <code><optional></code>.
336Groups of elements can be wrapped in <code><choice></code> to allow only one of them.
337The content of an <code><element></code> can be further nested elements, but note that
338elements may be reordered when loading an entity template:
339if you specify a sequence of elements it should be wrapped in <code><interleave></code>,
340so the schema checker will ignore reorderings of the sequence.
341
342For early development of a new component, you can set the schema to <code><ref name='anything'/></code> to allow any content.
343If you don't define @c GetSchema, then the default is <code><empty/></code> (i.e. there must be no elements).
344
345
346@subsection system-components System components
347
348System components are global singleton components of the @c SYSTEM_ENTITY.
349These are added to it in @c CComponentManager::AddSystemComponents, and