VgaGames4

VgaGames4 - sprite man-pages

[.. upper level ..]

# vg4->sprite->load()

Load sprite from file.

SYNTAX
struct VG_Sprite * vg4->sprite->load(const char *filename)
FUNCTION PARAMETERS

filename | File to load

RETURN VALUE
Returns loaded sprite or NULL = Error
DESCRIPTION
Load sprite from file. A sprite file is a text file, which describes the sprite. It consists of a header and one or more blocks of lines. Each block describes what vg4->sprite->next() will return. Format of the file: ------------------- Comments begin with #. Header line [SPRITE [<parameters>] ] where parameters are: - NLOOP=<number> # (optional:) default number of game-loops for each element (default = 1) - LIFETIME=<number> # (optional:) cycles, how often repeat the sprite before ending, or 0 = infinite (default) Examples: - [SPRITE] - [SPRITE NLOOP=3 LIFETIME=0] Block The block consists of one or more lines with <key>: <value> where the following lines must be indented Following keys are defined: - NLOOP (number or formula) number of game-loops for this element, or 0 = use default NLOOP number of header - IMAGE (filename, relative to the path of the sprite file or from the current directory when beginning with '/') image to load - ZOOM (number or formula) zoom factor of the image in percent (100 = default) - ROTATE (number or formula) rotating degrees of the image (0 to 359) - FLIP (string) flipping axe of the image: "V"=vertical, "H"=horizontal - BRIGHT (number or formula) brightness of the image (0=dark to VG_MAX_BRIGHTNESS, 100=default) - OPAQUE (number or formula) transparency of the image (0=transparent to 100=default) - SOUND (filename, relative to the path of the sprite file or from the current directory when beginning with '/') audio file to play (only wave or flac); within a REPEAT it will be played only once - SNDVOL (number or formula) volume of the sound (0 to 255, 100 = default) - SNDFLAG (string) STOP # play once, but at most until sprite cycle ends (default) WAIT # play once and wait for end before sprite cycle ends # (will be deactivated in network-games!) LOOPING # play looping Example: IMAGE: subdir/myimg.bmp FLIP: H ROTATE: 90 A block can be used repeatedly when the first key is REPEAT: - REPEAT (number or formula) number of repetitions, sets variable $repeat from 1 to REPEAT and variable $repeatmax to REPEAT Example: REPEAT: 30 IMAGE: subdir/myimg.bmp ROTATE: 90 + $repeat # from 91 to 120 For some keys of a block instead of a number a formula may be used: - There are following variables defined: - $repeat The number of the actual repetition of a block, from 1 to $repeatmax - $repeatmax How often a block shall be repeated - $nloop The header value NLOOP - A formula may have operators: + - * / % leading signs: + - negation: ! brackets: ( ) Examples: - ROTATE: 90 + $repeat - ROTATE: 90 + $repeat * 2 - ROTATE: ($repeatmax - $repeat) * 2
EXAMPLE

    /* just an example for a sprite file, will be played once */

    [SPRITE LIFETIME=1]

    # rotate img/myimg.bmp from 0 to 359
    REPEAT: 360
      IMAGE: img/myimg.bmp
      ROTATE: $repeat

    # rotate img/myimg.bmp from 359 to 180, play snd/sndback.wav once
    REPEAT: 180
      IMAGE: img/myimg.bmp
      ROTATE: -$repeat
      SOUND: snd/sndback.wav

    # just play snd/sndstop.wav, without an image
    SOUND: snd/sndstop.wav

    # show img/myimg.bmp rotated to 180 for 10 game-loops
    IMAGE: img/myimg.bmp
      ROTATE: 180
      NLOOP: 10

SEE ALSO
vg4 sprite show -h