Skip to content

NSL - NGEN SCRIPTING LANGUAGE

The NSL Engine Generator is a powerful tool that lets you create your own custom algorithms using a simple scripting language.

At it's core, the NSL Engine features a 32-step sequence (with individual pitch, velocity, length (in beats) and density per step) and standard parameters such Shift, Length and Density to control playback.

Instead of using a pre-defined algorithm to fill the 32-step sequence, the NSL Engine lets you load a script to generate it using your own custom algorithm.

Each NSL script consists of a series of hex values that are parsed into commands and values. Hex values above 160 (0xA0) trigger new commands and values below 160 are assigned as values / parameters for these commands. The engine also includes 32 registers (Memory Buffer) that can be used to store values and use them later in the script and 4 generic parameters (Param 1-4) with ranges from 0-100.

Warning

The NSL Engine is still in beta and it's not fully documented and implemented yet. This section of the manual will be updated as we continue to develop the NSL Engine. Faulty scripts can cause the NSL Engine to crash and require a reboot.

ngen_nsl Rust Library

ngen_nsl is a custom Rust library available via cargo / crates.io that make it easier to create and parse NSL scripts for the NSL Engine.

To add it to your Rust project, run the command cargo add ngen_nsl in your project's directory.

Documentation for ngen_nsl is available at https://docs.rs/ngen_nsl.

NSL Programming Reference

Parameter Types

NSL commands require set of different parameters to execute correctly and each parameter's value is used according to the list below:

VALUE

The VALUE parameter type returns a constant values from 0x00 to 0x7F (0-127) and values stored in the NSL Engine's memory buffer from 0x80 to 0x9F (128-159).

DESTINATION / SOURCE

The DESTINATION / SOURCE parameters consists of 2 x VALUE parameters that are used in pair to retrieve values from different parts and features of the NSL Engine.

SOURCE parameters are used to retrieve data while DESTINATION parameters are used to set data.

The first VALUE in the pair (aka VALUE 1) is used to indicate the type / location of the value that follows it (VALUE 2) according to the table below:

PART / FEATURE VALUE 1 (Address) VALUE 2 (Value / Index) VALUE 2 RANGE SOURCE DESTINATION DESTINATION RANGE
Constant Value 0x00 Value 0-127 ✔︎ ✕ N/A
Random Value 0x01 Random Range 0-127 ✔︎ ✕ N/A
Step Pitch 0x02 Step Number (Zero-Indexed) 0-31 ✔︎ ✔︎ 0-127 (MIDI PITCH)
Step Velocity 0x03 Step Number (Zero-Indexed) 0-31 ✔︎ ✔︎ 0-127 (MIDI VELOCITY)
Step Length 0x04 Step Number (Zero-Indexed) 0-31 ✔︎ ✔︎ 0-32 (BEATS)
Step Density 0x05 Step Number (Zero-Indexed) 0-31 ✔︎ ✔︎ 0-49
Memory Buffer 0x06 Step Number (Zero-Indexed) 0-31 ✔︎ ✔︎ 0-255
Params 1-4 0x07 Parameter Number (Zero-Indexed) 0-3 ✔︎ ✔︎ 0-100
Scale 0x08 Note position in scale 0-127 ✔︎ ✕ N/A
Scale (Quantized) 0x09 Note position in scale 0-127 ✔︎ ✕ N/A

Some features such as Constant and Random use the second VALUE in the pair (VALUE 2) as the actual value while the other types use it as an index to indicate the location of the value in the NSL Engine's memory.

Examples:

  • 0x00 0x05 : Returns a constant value (ORIGIN = 0x00) of 5 (VALUE = 0x05).
  • 0x02 0x10 : Returns the step pitch (ORIGIN = 0x02) at index 16 (VALUE = 0x10).
  • 0x07 0x20 : Returns a random value (ORIGIN = 0x07) between 0 and 32 (VALUE = 0x20).

INT16

The INT16 parameter type uses a pair (x and y) of 8-bit values (0-255) to create a 16-bit value (0-65535) by shifting the first value 8 bits to the left and adding the second value to it ((x << 8) + y).

List of Commands

0xA1 SET

Description: Sets the value of a destination to the value of a source.

Parameters: DESTINATION SOURCE

Examples:

  • 0xA1 0x02 0x00 0x01 0x10 : Sets the pitch of step 1 to a random value between 0 and 16.

  • 0xA1 0x03 0x00 0x03 0x01 : Sets the velocity of step 1 to the velocity of step 1.

  • 0xA1 0x06 0x00 0x05 0x04 : Sets the value of the memory buffer at index 0 to the density of step 5.

0xB0 ADD

Description: Adds the value of a source to a destionation.

Parameters: DESTINATION SOURCE

Examples:

  • 0xB0 0x02 0x00 0x00 0x2 : Add 2 (0x00 0x02) to the pitch of the first step (0x02 0x00).

0xB1 SUBTRACT

Description: Subtracts the value of a source from a destination.

Parameters: DESTINATION SOURCE

Examples:

  • 0xB1 0x02 0x00 0x01 0x10 : Subtract a random value between 0 - 16 (0x01 0x10) from the pitch of the first step (0x02 0x00).

0xC0 LOOP SET

Description: Enables looping and set the loop count to the value of a source.

Parameters: SOURCE (Loop Count)

Examples:

  • 0xC0 0x00 0x03 : Enables looping and set the loop count to 3.

0xC1 LOOP END

Description: Ends the current loop.

Parameters: None

0xC2 JUMP

Description: Jumps to a specific position in the program.

Parameters: INT16 (Jump Position)

Examples:

  • 0xC2 0x02 0x24 : Jumps to position 548.

0xFF END

Description: Ends the program.

Parameters: None

[ MORE INFORMATION COMING SOON ]