README_SCRIPTING.markdown

# Scripting

Patterns and levels must be scripted using LUA. LUA is a versatile scripting language that allows the user to create any kind of pattern.

http://www.lua.org/manual/5.1/manual.html

There are many LUA editors that can check your syntax and make you avoid typos: I use http://sourceforge.net/projects/luaedit/

## Hardcoded LUA commands

These commands can be called like any other function. They are hardcoded because they directly communicate with the C++ engine.

`log(mLog)` Sends a log message to the console. Very useful for debugging!

`getSides()` Returns the current number of sides.

`getSpeedMult()` Returns the current speed multiplier.

`getDelayMult()` Returns the current delay multiplier.

`execScript(mFilename)` Executes another LUA file. Can both be used to include useful functions, and to execute a series of commands. Example: `execFile("test.lua")`

`wait(mDuration)` Makes the pattern timeline wait `mDuration` frames. This will halt pattern spawning. If the timeline has no more commands, the `"lua_file"` of the level is executed again from the beginning.

`wall(mSide, mThickness)` Creates a wall with default speed, at side `mSide`, with thickness `mThickness`. Useful wall creation functions are commonly defined in `common.lua` and `commonpatterns.lua`.

`wallAdj(mSide, mThickness, mSpeedAdj)` Creates a wall with default speed multiplied by `mSpeedAdj`, at side `mSide`, with thickness `mThickness`.

`execEvent(mId)` Executes an event file with id `mId` immediately. Similar to event command `"event_exec"`.

`enqueueEvent(mId)` Enqueues an event file with id `mId`. Similar to event command `"event_enqueue"`.

`getLevelValueInt(mValueName)` `getLevelValueFloat(mValueName)` `getLevelValueString(mValueName)` `getLevelValueBool(mValueName)` `setLevelValueInt(mValueName, mValue)` `setLevelValueFloat(mValueName, mValue)` `setLevelValueString(mValueName, mValue)` `setLevelValueBool(mValueName, mValue)` Manipulate the current level values. This allows you to change any value that is present in the level .json file. You can also create new values and use them as 'global variables' for your LUA scripts. Nothing will be saved to the actual .json file, it only works in memory.

`getStyleValueInt(mValueName)` `getStyleValueFloat(mValueName)` `getStyleValueString(mValueName)` `getStyleValueBool(mValueName)` `setStyleValueInt(mValueName, mValue)` `setStyleValueFloat(mValueName, mValue)` `setStyleValueString(mValueName, mValue)` `setStyleValueBool(mValueName, mValue)` Manipulate the current style values. This allows you to change any value that is present in the style .json file. You can also create new values and use them as 'global variables' for your LUA scripts. Nothing will be saved to the actual .json file, it only works in memory.

`playSound(mId)` Plays a sound with id mId.

`forceIncrement()` Increments the level difficulty.

`messageAdd(mMessage, mDuration)` Adds a message to the message queue.

`messageImportantAdd(mMessage, mDuration)` Adds an important message to the message queue.

`getDifficultyMult()` Gets the automatic difficulty variant multiplier.

`isKeyPressed(mKey)` Returns true if mKey is pressed. 0=A, 1=B, 3=C... (refer to http://www.sfml-dev.org/documentation/2.0/classsf11Keyboard.php)

`isFastSpinning()` Returns true if the game is currently doing a "fast spin".

## Hardcoded level LUA functions

These functions are REQUIRED in level script files.

`function onLoad() ... end` This functions runs when the level starts or is restarted.

`function onStep() ... end` This function runs when the level timeline is empty. You should place your pattern selection logic here.

`function onIncrement() ... end` This function runs when the difficulty is incremented.

`function onUnload() ... end` This function runs when the level is closed or restarted.

`function onUpdate(mFrameTime) ... end` This function runs every frame.