"Document data object" means an object which is described here by using "secondary header" (header 2) type headers. Inner structures of objects have "header 3" headers. But actually the "header 2" formatting is nearly the same as "header 3" so this distinction is not easily readable.

Root

Root object of the document. Contains all data that is part of the document.

  • particle_templates: Set of all particle templates in the document.
  • emitter_templates: Set of all emitter templates in the document.
  • shooters: Set of all shooter objects in the document.
  • groups: Set of all group objects in the document, except the root group.
  • root_group: The single special root group object.
  • child: Maps a list of objects to an object. The value list contains the children of the key object. Only objects are contained here that have a non-empty child list.
  • parent: Maps a list of objects to an object. The value list contains the parents of the key object. All objects should be here because all objects have at least one parent (except the root group).

There is a parent-child relationship between the objects. Every object in the document should have at least a single parent object, except the root group which has no parent. The child and parent members are together representing the parent-child relationships. The child is "inverse" of the parent, theoretically only one of these is needed but maintenance is more easy if the both directions are stored. The parent-child graph should contain no loops, no circles, no parallel edges, but is not a tree. An object can have multiple parents and there can be multiple paths between two objects (but no parallel edges). (Direction of the edges goes from parent to child.) The root group of the document must always exist. There is a function called test_invariant that should check for all error conditions but it is not perfectly implemented.

Group

An object used only to contain other objects. (Not only a group may contain other objects, but any other object (ParticleTemplate and the others) too. The group is a separate object that is used only for grouping.)

  • name: Name of the group.

ParticleTemplate

Defines a class of particles in the animation. Random values are evaluated once for every new particle of the class.

  • name: Name of the particle class.
  • visible: Is the particle visible (independently of its other behaviors)? If not, the particle is not drawn but exists like if it were drawn.
  • lifetime: Lifetime of the particles. This is specified as a possibly random value.
  • density: Property for particle movement.
  • gravitation_enabled: Is gravitation enabled in movement calculation?
  • friction_enabled: Is "fluid friction" enabled in movement calculation?
  • shape: Shape of the particle polygon (may be point, drawn as line, as rectangle, and possibly others).
  • texturefile: Name of an image file to use as texture on the drawn polygon.
  • tile related members: Control how the texture appears on the drawn polygon. The texture file may contain a list of images that are used for texture animation.
  • time_marks: Set of objects to define specific points in time during the particle lifetime. Control points of curves of other parameters use these points. The time marks are there identified by their name strings. These names are stored only here as map keys but not in the time mark structure.
  • color, alpha, size, radius control points: Curves to define the color, alpha, size and radius of the drawn particle. Every of these defines the specific property and how it changes in time. If the list contains one element, this is used as static value. Otherwise the list defines a piecewise linear curve. A control point contains a reference to a time mark and a value which may be random. Control points should follow in increasing points in time to have the animation work properly. The first and last points in the sequence define always the first and last points and are positioned automatically at particle time 0 and lifetime. These should have an empty time mark name. The same applies when only one control point is specified (no animation).
  • emitter_blocks: A list of "emitter data block" structures that defines how the particle generates new particles.

TimeMark

Defines a point in time, used for a particle class.

  • mode: For from_start, time is counted from the start of the particle. For from_end, time is counted backwards from death of the particle. For from_other, time is counted relative from an other time mark, that is indicated by other.
  • time: Time value for the time mark. Can be a random value. This is used to define the point in time as indicated by mode.
  • other: Points out an other time mark in the same particle template. Used if mode is from_other.

The time mark has a string name which is not stored in the structure itself, only at the map of time marks in the particle template.

FloatControlPoint, ColorControlPoint

Control points in curves for color or float values.

  • time: Time for the control point. The name of a time mark in the particle template that contains the curve.
  • value: Value of the control point. Possibly random.

EmitterBlock

An "emitter data block" in a particle template. Defines how the particle generates new particles. A particle can contain multiple such emitter blocks.

  • name: A name for the emitter block.
  • time1, time2: Specify two time values through time marks. Contain names of the time marks on the particle template where the emitter block itself is contained. If time2 is empty only a single point in time is used. Otherwise these define a time interval where the emit process is triggered at start and after a random time between interval_min and interval_max has elapsed since the last trigger.
  • interval_min, interval_max: Values for a time interval used for repetitive triggering.
  • emitter: Specifies an emitter template to use.

EmitterTemplate

Defines a way of how to create new particles. An emitter template is used to construct imaginary "emitter" objects that create particle objects. The emitter template is the "class" of these emitter objects, similar as the particle template is class of the particles. The imaginary emitter object exists only for the purpose of creating new particles in the way defined by the emitter template. The particles (for example) store references to emitter templates. If the particle should generate new particles (at a specific point in time) the emitter template is requested to create a new emitter object and that object is "triggered", that is, the particles are actually created. The emitter is then immediately destroyed. For a new triggering a new one is created. The emitter object can be seen as a "shell" ("bomb") and the emitter template as a class of shells.

  • name: Name of the emitter template.
  • emitter_blocks: List of "emitter data block" structures.

EmitterBlock

Emitter data block in EmitterTemplate.

  • name: A name for the emitter block.
  • amount: Number of particles to generate or number of times to invoke the specified emitter template.
  • position, angle, angular_velocity: Specify these parameters of the new particles. They can be random values, recalculated for every particle. These values are used to calculate these properties of the generated particles.
  • scale: Additional scale factor for the particle velocity.
  • synchronized: If both a particle template and an emitter template are specified, indicates if the same movement values (position, velocity, ...) should be used for the both or these should be recalculated for the two objects.
  • particle: Specifies a particle template to use for creating new particles.
  • emitter: Specifies an emitter template to use. The calculated particle parameters are passed to the emitter at triggering, the emitter will use these as the "inherited" values.


More about the parameters is described at page "particle movement".

Shooter

Class of objects that create particles at a fixed point in time or in some other ways, but without the need to be "triggered" by another particle or emitter. The shooter is the object that initially creates particles or triggers an emitter. The particle animation consists of shooters that create particles, possibly by using emitters. And the particles and emitters create other ones. The shooters are not used as templates in the sense as for ParticleTemplate and EmitterTemplate. Every instance is "the template for itself". Every shooter has a "start time" that is the point in time when the shooter starts to do something at all. The shooter works the for a time interval (which can be of zero length).

The shooter is an abstract type. Currently one concrete type of shooter exists, the ParticleShooter. This works by creating one instance of a particle of a specific particle template with specific parameters.

Last edited Dec 19, 2011 at 4:45 PM by fruitfruit, version 13

Comments

No comments yet.