If you want to use scripting in [[Simple_Level|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 [http://blinkensisters.svn.sourceforge.net/viewvc/blinkensisters/lostpixels/game/software/BASEDATA/LEVELS/ SVN-Repository]) to see some example scripts! If you need more BlinkenSisters specific commands, feel free to use our [http://sourceforge.net/tracker/?group_id=156792 Tracking-System] at SourceForge.


Scripting is based on LUA, see the [http://www.lua.org LUA Homepage] for basic syntax.
== 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)

=== 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

=== 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 pixels), 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.

