OldScripting

From BlinkenSisters

---

This Pages describes how to use the the old LUA-bindings. Those are deprecated and support will be finished with one of the next releases. Use the new OO-LUA-Bindings instead!

---

If you want to use scripting in your new Level, you have to place the following line at the end of your levelN.conf:

script=levelN.bsl

levelN.bsl is the file where you put your script in.

Take a look at existing .bsl-files (e.g. in the BlinkenSisters-Folder in your home-directory or in our SVN-Repository) to see some example scripts! If you need more BlinkenSisters specific commands, feel free to use our Tracking-System at SourceForge.

Scripting is based on LUA, see the LUA Homepage for basic syntax.

Contents 1 The following commands are specific to BlinkenSisters: 1.1 Meta commands 1.1.1 Die(err) 1.2 Object handling 1.2.1 gfxhandle = LoadGFX(gfxname) 1.2.2 objhandle = AddObject(gfxhandle, x, y, blocking, visible, ontop, killing) 1.2.3 SetGFX(objhandle, gfxhandle) 1.2.4 SetObjPos(objhandle, x, y) 1.2.5 SetVisible(objhandle, visible) 1.2.6 SetBlocking(objhandle, blocking) 1.2.7 SetOnTop(objhandle, ontop) 1.2.8 SetKilling(objhandle, killing) 1.2.9 SetElevator(objhandle, elevator) 1.2.10 SetPixel(objhandle, isPixel) 1.3 Player handling 1.3.1 SetGravity(gravity) 1.3.2 SetFreeMovement(freemovement) 1.3.3 SetPlayerX(x) 1.3.4 SetPlayerY(y) 1.3.5 GetPlayerX() 1.3.6 GetPlayerY() 1.3.7 KillPlayer() 1.4 Sound handling 1.4.1 fxhandle = LoadSoundFX(fxname) 1.4.2 PlaySoundFX(fxhandle) 1.5 Level functions 1.5.1 IncMaxPixels(count) 1.5.2 count = GetRequiredPixelCount() 1.5.3 SetRequiredPixelCount(count) 1.5.4 count = GetCollectedPixelCount() 1.5.5 SetCollectedPixelCount(count) 1.5.6 AddPixel(x, y) 1.5.7 AddGFXPixel(gfxobj, x, y) 1.5.8 AddBonusLive(x, y) 1.5.9 SetLockedBG(locked) 1.5.10 PlayVideo(filename, trackergui) 1.5.11 SetSpecialTiles(paint) 1.5.12 SetCanExit(canexit) 1.5.13 GetCanExit() 1.5.14 GetCanExit() 1.5.15 SetOutputFilter(filter) 1.6 Triggers 1.6.1 triggerobj = AddFGTrigger(gfxobj, x, y, funcname, active, visible) 1.6.2 SetTriggerActive(triggerobj, active) 2 Required functions/callbacks for BlinkenSisters 2.1 initLevel() 2.2 scriptPhysics() 2.3 handleAction(objhandle)

The following commands are specific to BlinkenSisters:

Meta commands

Die(err)

Quits BlinkenSisters with an error-string "err"

Object handling

gfxhandle = LoadGFX(gfxname)

Loads graphic-file gfxname and returns its handle

objhandle = AddObject(gfxhandle, x, y, blocking, visible, ontop, killing)

Add an object with graphic gfxhandle at coordinates x/y (in tile-coords)

• Object can be blocking (=1) or non-blocking (=0)
• Object can be visible (=1) or non-blocking (=0) (Invisible objects are ALWAYS non-blocking)
• Object is rendered normal (=0) or on top of everything (=1)
• Object can kill the player (=1) or doesn't (=0)

SetGFX(objhandle, gfxhandle)

Sets graphics for an object objhandle to graphic gfxhandle

SetObjPos(objhandle, x, y)

Sets coordinates x and y for an object objhandle (Coordinates are pixel- not tilecoordinates for better control)

SetVisible(objhandle, visible)

Sets the visibility of an object

SetBlocking(objhandle, blocking)

Sets the blocking property of an object

SetOnTop(objhandle, ontop)

Sets the ontop property of an object

SetKilling(objhandle, killing)

Sets the killing property of an object

SetElevator(objhandle, elevator)

Sets the elevator property of an object. This is used by the engine for smoother downwars rides because it changes the way gravity works when standing on this object

SetPixel(objhandle, isPixel)

Sets the pixel property of an object (i.e. make object a pixel)

If the Player collects the Pixel, GetCollectedPixelCount() will be increased.

GetRequiredPixelCount() is not affected by this function. You may want to use IncMaxPixel() or SetRequiredPixelCount().

Player handling

SetGravity(gravity)

Sets, if the player feels gravity

SetFreeMovement(freemovement)

Sets, if the player can move freely in all directions

SetPlayerX(x)

Sets the x coordinate of the player sprite (Coordinates are pixel- not tilecoordinates for better control)

SetPlayerY(y)

Sets the y coordinate of the player sprite (Coordinates are pixel- not tilecoordinates for better control)

GetPlayerX()

Returns the x coordinate of the player sprite (Coordinates are pixel- not tilecoordinates for better control)

GetPlayerY()

Returns the y coordinate of the player sprite (Coordinates are pixel- not tilecoordinates for better control)

KillPlayer()

The player dies and loses one life

Sound handling

fxhandle = LoadSoundFX(fxname)

Load sound effect fxname and returns its handle

PlaySoundFX(fxhandle)

Plays the sound with fxhandle

Level functions

IncMaxPixels(count)

Increments the pixelcount needed to finish the level by count

count = GetRequiredPixelCount()

Returns the number of pixels required to finish the level.

SetRequiredPixelCount(count)

Sets the number of pixels required to finish the level.

count = GetCollectedPixelCount()

Returns the number of pixels the user has collected so far.

SetCollectedPixelCount(count)

Sets the number of pixels the user has collected so far.

AddPixel(x, y)

Adds a pixels at x/y Does NOT increment the pixelcount needed to finish the level

AddGFXPixel(gfxobj, x, y)

Adds a pixels OBJECT at x/y with GFX gfxobj Does NOT increment the pixelcount needed to finish the level

AddBonusLive(x, y)

Adds a bonus live object at x/y

SetLockedBG(locked)

Locks the background to scroll same as foreground (disables parallax scrolling)

PlayVideo(filename, trackergui)

Plays a BMF-Movie with "filename"

You can turn the trackergui on (=1) or off (=0)

SetSpecialTiles(paint)

Turns on/off painting of special tiles (Start, Finish, etc)

SetCanExit(canexit)

Turns on/off the ability of the player to finish the level

GetCanExit()

Returns 0/1 if the player can finish the level

GetCanExit()

Returns 0/1 if the player can finish the level

SetOutputFilter(filter)

Sets Filter for the whole display. filter is one of the following values or a sum of some of them:

• OUTPUTFILTER_NONE ... normal
• OUTPUTFILTER_GREYSCALE ... b/w
• OUTPUTFILTER_COLORINVERT ... inverted colors
• OUTPUTFILTER_NOISERECT ... Noise with rectangles
• OUTPUTFILTER_NOISECIRCLE ... Noise with circles
• OUTPUTFILTER_NOISESTRIPE ... Noise with stripes

e.g. SetOutputFilter(OUTPUTFILTER_GREYSCALE); or SetOutputFilter(OUTPUTFILTER_COLORINVERT + OUTPUTFILTER_NOISECIRCLE);

Note that at present all noise-effects are frame-rate depending.

Triggers

triggerobj = AddFGTrigger(gfxobj, x, y, funcname, active, visible)

Adds a trigger object with GFX gfxobj at coords x/y. Sets the states "active" and "visible". If the trigger object is active and the player has a "collission" with it (e.g. overlapping non-transparent Pixel), the function with name given by funcname is called.

SetTriggerActive(triggerobj, active)

Sets the on/off state of the given triggerobj.

Required functions/callbacks for BlinkenSisters

initLevel()

This is called on level initialization. This is where you pre-load sounds and graphics.

scriptPhysics()

This is called 100 times/second. Here you can handle all your cyclic events

handleAction(objhandle)

Whenever the user presses the Action-key on top of an object, this function is called with the appropriate object handle.