BOBEmitter ‐ API

Emitter.init()

Param:  None
Return: None

Initializes the BOBEmitter class and must be called before the BOBEmitter is used.

It prepares the class to handle 5 independent emitters. The value can be changed by modifying the constant CONST MAX_EM in the source.

Emitter.new(x!,y!,n%) as Integer

Param:  x,y = position of the emitter
        n   = number of particles to be used
Return: emitter handle or -1, if no emitter is free

This method creates and initializes a new BOBEmitter at position (x!,y!). Furthermore, the number of BOBs (particles) that should be handled by this emitter will be allocated.

The class is designed to handle 1000 BOBs (particles). From this pool, the emitter will allocate the desired number of BOBs.

The number of BOBs can be changed in the source by modifying the constant CONST MAX_BOB, but be aware of the performance implications. Reducing the number will save some memory.

Emitter.free(eh%)

Param:  eh  = emitter handle
Return: None

This method frees the image buffers of an emitter, which can then be used again in this or other emitters.

Buffer management for BOBs has not been implemented yet. Therefore, the number of BOBs will not change.

Emitter.setBOB(eh%,px%,py%,bobw%,bobh%,p%)

Param:  eh        = emitter handle
        px,py     = position of the BOB image on image page
        bobw,bobh = width and height of the BOB image
        p         = video page where the BOB images are stored
Return: None

This method defines the BOB image in width and height and where it is located on the image page. The buffered emitter will read the image data into a free buffer.

Emitter.setPos(eh%, X!, Y!)

Param:  eh    = emitter handle
        x, y  = new position of the emitter
Return: None

This method moves the emitter to a new location. New BOBs will spawn from this position.

Emitter.setTarget(eh%, X!, Y!, steps%)

Param:  eh    = emitter handle
        x, y  = position where the emitter should move to
        steps = number of cycles in which the target position will be reached
Return: None

This method sets the target position of the emitter. The emitter will slowly move towards this position. The travel speed can be defined with the steps parameter. The bigger steps is, the slower the movement.

Emitter.setCallback(eh%, type%, cb$)

Param:  eh   = emitter handle
        type = callback type, can be CB_NEW, CB_UPDATE or CB_DONE
        cb   = callback function/sub name
Return: None

At certain states the BOBEmitter can call a function of the caller's code to allow certain adjustments of the BOBs' behavior. Three callbacks are supported so far:

• CB_NEW(idx) - called after BOB creation, idx = index to address the BOB
• CB_UPDATE(idx) - called after BOB update, the new position and the life property are handled by BOBEmitter. All other behavioral changes can be done in this callback. Please keep in mind that this callback is called at every update for every BOB, so the performance impact is huge. idx = index to address the BOB
• CB_DONE(flag) - called after all BOBs have died or the emitter has reached the target pos. flag = 0 - all BOBs died, flag = 1 - emitter reached target

Emitter.setInterval(eh%, arg!)

Param:  eh  = emitter handle
        arg = interval for new BOBs (particles) in milliseconds
Return: None

This method defines how fast new particles should be created. If set to zero, the emitter will create a new BOB for any free slot in its BOB list immediately. They all appear at once.

If this parameter is set to a number, new particles will be created every x milliseconds, so you get a constant stream of new particles.

Emitter.on(eh%)

Param:  eh = emitter handle
Return: None

Sets an emitter in active mode. It will immediately start spawning BOBs.

Emitter.off(eh%)

Param:  eh = emitter handle
Return: None

Switches an emitter off. All associated BOBs will disappear instantly from the screen.

Emitter.respawn(eh%, flag%)

Param:  eh   = emitter handle
        flag = indicates if expired BOBs should respawn automatically
Return: None

This method sets a flag that tells the emitter whether expired BOBs should be replaced with new ones.

This is also a proper method to let an emitter die smoothly. Switch off respawning and wait until all BOBs have died. Then switch the Emitter off in the CB_DONE callback.

Emitter.update(eh%)

Param:  eh = emitter handle
Return: None

This method updates the emitter and all associated BOBs for the next drawing cycle.

This method must be called regularly in the game loop.

Emitter.draw(eh%)

Param:  eh = emitter handle
Return: None

This method draws an emitter and all associated BOBs on the active write page.

This method must be called regularly in the game loop.