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 modifing 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 handeled 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 changes in the source by modifing the constant CONST MAX_BOB, but be aware of the performance implications. Reducing the number will save some menmory.

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.

A buffer management for BOBs have 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 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 the slower is 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 callers code to allow certain adjustments of the BOBs behaviour. 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 died or emitter reached target pos. flag = 0 - all BOBs died, flag = 1 - emiter 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 his BOB list immideately. They all apear at once.

This 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 immideately start spawning BOBs

Emitter.off(eh%) Param: eh = emitter handle Return: None

Switches an emitter off. All associated BOBs will disapear 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 if or if not expired BOBs should be replaced with new ones.

This is also a proper method to let an emitter smothly die. Switch of 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 regularly called in the game loop

Emitter.draw(eh%) Param: eh = emitter handle Return: None

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

This method must be regularly called in the game loop