+ We already came across various built-in functions, which you may call + by your scripts to perform certain tasks or behavior which is already + provided for you by the sampler. When working on larger scripts, you + may notice that you easily get to the point where you may have to + duplicate portions of your script code, since there are certain things + that you may have to do again and again in different parts of your script. + Software developers usually try to avoid such code duplications to + keep the overall amount of code as small as possible, since it would + make the software very hard to maintain. One way for you to avoid such + script code duplications with NKSP is to write so called User Functions. +
++ Let's assume you wanted to create a simple stuttering effect. You may do so + like in the following example. +
+
+on note
+ while (1)
+ wait(200000)
+ if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
+ exit()
+ end if
+ change_vol($EVENT_ID, -20000) { Reduce volume by 20 dB. }
+ wait(200000)
+ if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
+ exit()
+ end if
+ change_vol($EVENT_ID, 0) { Increase volume to 0 dB. }
+ end while
+end on
+
+
+ This script will run an endless loop for each note being triggered.
+ Every 200ms it will turn the volume alternatingly down and
+ up to create the audible stuttering effect. After each wait()
+ call it calls event_status($EVENT_ID) to check whether
+ this note is still alive, and as soon as the note died, it will stop
+ execution of the script instance by calling exit(). The latter
+ is important in this case, because otherwise the script instances would
+ continue to run in this endless loop forever, even after the respectives
+ notes are gone. Which would let your CPU usage to increase with every note.
+ This behavior of the sampler is not a bug, it is intended, since there may
+ also be cases where you want to do certain things by script even after the
+ respective notes are dead and gone. However as you can see, that script is
+ using the same portions of script code twice. To avoid that, you could also
+ write the same script with a user function like this:
+
+function pauseMyScript
+ wait(200000)
+ if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
+ exit()
+ end if
+end function
+on note
+ while (1)
+ call pauseMyScript
+ change_vol($EVENT_ID, -20000) { Reduce volume by 20 dB. }
+ call pauseMyScript
+ change_vol($EVENT_ID, 0) { Increase volume back to 0 dB. }
+ end while
+end on
+
+
+ The script became in this simple example only slightly smaller, but it also
+ became easier to read. And in practice, with a more complex script, you can
+ reduce the overall amount of script code a lot this way. You can choose any
+ name for your own user functions, as long as the name is not already
+ reserved by a built-in function. Note that for calling a user function,
+ you must always precede the actual user function name with the
+ call keyword. Likewise you may however not use the
+ call keyword for calling any built-in function. So that
+ substantially differs calling built-in functions from calling user functions.
+
A programming language provides so called operators to perform