4.10.12 Sprite2D Mesh Object

Written by Jorrit Tyberghein, ([email protected]).

A 2D Sprite is basically a polygon that always faces the camera. There are some special effects that you can do with this but it is really very simple otherwise.

Basic Structure

The following SCF class names are used (for csLoadPlugin):

• Type plugin: `crystalspace.mesh.object.sprite.2d'
• Loader plugin: `crystalspace.mesh.loader.sprite.2d'
• Factory loader plugin: `crystalspace.mesh.loader.factory.sprite.2d'

Objects in this plugin implement the following SCF interfaces (get with scfQueryInterface):

• MeshObject
  • Implements `iMeshObject'
  • Implements `iSprite2DState'
  • Implements `iParticle'
• MeshObjectFactory
  • Implements `iMeshObjectFactory'
  • Implements `iSprite2DFactoryState'
• MeshObjectFactory
  • Implements `iMeshObjectType'

Factory State Interface

Use the SCF interface `iSprite2DFactoryState' to access settings for a 2D sprite factory. The definition of this interface can be found in `CS/include/imesh/sprite2d.h' and that is also the include file you need to include in your applications to use this plugin. Using this interface you can access the material, blending mode (mixmode), and lighting settings.

Factory Loader

<lighting>yes/no</lighting>

Enable/disable lighting.

<material>materialname</material>

Material to use for the polygon.

<mixmode><mode /></mixmode>

Blending mode; one of `add', `alpha', `copy', `keycolor', `multiply2', `multiply', or `transparent'.

<uvanimation name=uvanimationname><frame ...> ...

Define an uv animation, that is a sequence of frames which textures are all in one big texture. Thus the animation is achieved by altering the (u,v) coordinates of the polygon defined by this sprite.

<frame><duration><vertices ...> ...

Defines a single frame within an uv animation by specifying its duration in milliseconds and the u,v coordinates to use.

• <frame name="framename"> <duration>milliseconds</duration> <v u="" v="" /> ... u,v coo list </frame>

Object State Interface

`iSprite2DState' is the SCF interface that you can use to set/get settings for a 2D sprite object. The definition of this interface can be found in `CS/include/imesh/sprite2d.h' and that is also the include file you need to include in your applications to use this plugin. Using this interface you can access the material, blending mode (mixmode), lighting settings, and also the vertices of the 2D polygon controlled by this plugin.

Object Loader

<factory>factoryname</factory>

Name of the factory to use for creation of this instance.

<mixmode><mode /></mixmode>

Blending mode, one of `add', `alpha', `copy', `keycolor', `multiply2', `multiply', or `transparent'.

<material>materialname</material>

Material to use for the polygon.

<lighting>yes/no</lighting>

Enable/disable lighting.

vertices <v x="" y="" /> ...

List of 2D vertices defining the polygon.

<uv u="" v="" />

List of texture mapping UV coordinates for the polygon.

<color red="" green="" blue="" />

List of rgb colors for the polygon.

<animate> ...

Select an uv animation from the list of animations declared in the template

• <animate name="animationname"> <timing>milliseconds</timing> <loop>yes/no</loop> </animate>

  • timing > 0 : every <timing> milliseconds the next frame will be shown
  • timing < 0 : every <-timing> gameloop the next frame will be shown
  • timing = 0 : timing attached to the frame will be used
  • loop : loop the animation or stop after last frame (and show the last frame)

Example 1

This is how our world file looks:

<world>
  <textures>
    <texture name="blow">
      <file>blow.png</file>
    </texture>
  </textures>
  <materials>
    <material name="explosion">
      <texture>blow</texture>
    </material>
  </materials>
  <meshobj name="Explosion">
    <plugin>crystalspace.mesh.loader.factory.sprite.2d</plugin>
    <params>
      <material>explosion</material>
      <uvanimation name="boom">
        <frame name="first">
          <duration>100</duration>
          <v u="0" v="0" />
          <v u="0.5" v="0" />
          <v u="0.5" v="0.5" />
          <v u="0" v="0.5" />
        </frame>
        <frame name="second">
          <duration>100</duration>
          <v u="0.5" v="0" />
          <v u="1" v="0" />
          <v u="1" v="0.5" />
          <v u="0.5" v="0.5" />
        </frame>
        <frame name="third">
          <duration>100</duration>
          <v u="0" v="0.5" />
          <v u="0.5" v="0.5" />
          <v u="0.5" v="1" />
          <v u="0" v="1" />
        </frame>
        <frame name="fourth">
          <duration>100</duration>
          <v u="0.5" v="0.5" />
          <v u="1" v="0.5" />
          <v u="1" v="1" />
          <v u="0.5" v="1" />
        </frame>
      </uvanimation>
    </params>
  </meshobj>
  <sector name="space">
  <!-- define all the stuff in space ...
       and now one of the enemies right after we met him -->
    <meshobj name="Kaboom">
      <plugin>crystalspace.mesh.loader.sprite.2d</plugin>
      <params>
        <v x="-1" y="1" />
        <v x="1" y="1" />
        <v x="1" y="-1" />
        <v x="-1" y="-1" />
        <uv u="0" v="0" />
        <uv u="1" v="0" />
        <uv u="1" v="1" />
        <uv u="0" v="1" />
        <color red="1" green="1" blue="1" />
        <color red="1" green="1" blue="1" />
        <color red="1" green="1" blue="1" />
        <color red="1" green="1" blue="1" />
        <lighting>no</lighting>
        <!-- show the animation, use the timings attached to
             the frames, loop -->
        <animate name="boom">
          <timing>0</timing>
          <loop>yes</loop>
        </animate>
      </params>
      <move>
        <v x="0" y="0" z="0">
      </move>
    </meshobj>
  </sector>
</world>

This document was generated using texi2html 1.76.