OMSI Script (.DLL)

Introduction

The public class Runspace represents an OMSI Script runspace with invocable command blocks. It provides functionality for managing command blocks, stacks, variables, constants, functions, triggers, and debugging within the OMSI Script environment.

The class has multiple constructors allowing customization of the runspace with different stacks, variables, and contexts. By default, it initializes with an empty list of command blocks and stacks for floating-point values, a registry stack, and string values. It also provides contexts for variables, system variables, constants, linear functions, triggers, and debugging.

Setting up the project

Visual Studio project creation

Open Visual Studio and create a new project by selecting "File" -> "New" -> "Project". In the "New Project" window, select "Visual C#" and then "Console App (.NET Framework)" as the project type. Give your project a name, such as "TestOMSIScriptApp", and choose a location to save it. Click "Create" to create the project.

Add reference in Visual Studio

Right-click on the solution and select "Add Reference".

Visual Studio reference manager

In the "Reference Manager" window, select "Browse" and navigate to the location of your DLL file. Select the DLL file and click "Add". Click "OK" to close the "Reference Manager" window.

C# using statement

Now, in your code file, you can add a "using" statement to reference the namespace of the DLL: using OMSIScript;

Use DLL classes and methods

You can now use the classes and methods from the DLL in your code.

Runspace Class

Represents an OMSI Script runspace with invocable command blocks.

Constructors

  • Runspace(CommandBlock? defaultCommandBlock = null)

    Initializes a new OMSI Script runspace with invocable command blocks.

    Parameters:

    • defaultCommandBlock - The default command block to use when none is specified. This is useful for console applications, for example, which do not require a {frame} block.
  • public Runspace(CommandBlock? defaultCommandBlock = null, IStack ? floatStack = null, IStack ? registryStack = null, IStack ? stringStack = null, IVariablesContext ? floatVariables = null, IVariablesContext ? stringVariables = null, ISystemVariablesContext? systemVariablesContext = null, IConstantsContext? constants = null, ILinearFunctionsContext? linearFunctions = null, ITriggersContext? triggersContext = null, IDebugContext? debugContext = null)

    Initializes a new OMSI Script runspace with specified parameters.

    Parameters:

    • defaultCommandBlock - The default command block to use when none is specified. This is useful for console applications, for example, which do not require a {frame} block.
    • Other parameters - These are useful if you want to implement the components of the runspace yourself. Otherwise, the pre-created classes under OMSIScript.Context can be used.

Methods

  • void AddCommandsFromLine(params string[] lines)

    Parses and adds commands from the specified lines to the command blocks.

    Parameters:

    • lines - The lines containing commands to be parsed and added.
  • CommandBlock FindOrAddCommandBlock(string name, CommandBlock.BlockType type)

    Retrieves or adds a command block based on the specified name and type.

    Parameters:

    • name - The name of the command block.
    • type - The type of the command block.

    Returns:

    The retrieved or newly added command block.

  • bool TryFindCommandBlock(string name, CommandBlock.BlockType type, [MaybeNullWhen(false)] out CommandBlock commandBlock)

    Attempts to locate a command block within the runspace.

    Parameters:

    • name - The name of the command block.
    • type - The type of the command block.
    • commandBlock - If found, the located command block; otherwise, null.

    Returns:

    True if the command block was found; otherwise, false.

  • void Invoke(CommandBlock commandBlock)

    Executes the specified command block.

    Parameters:

    • commandBlock - The command block to be invoked.
  • static void AddCommand(CommandBlock? commandBlock, string command)

    Appends a command to the specified command block.

    Parameters:

    • commandBlock - The target command block to which the command will be added.
    • command - The command to be appended.

    Exceptions:

    • ArgumentNullException - Thrown when the commandBlock parameter is null.

CommandBlock Class

Represents an init, frame, frame_ai, trigger or macro block with the commands.

Example

var commandBlock = new CommandBlock("frame", CommandBlock.BlockType.Frame);
var stringVariablesContext = new StringVariablesContext();

var runspace = new Runspace(commandBlock, stringVariables: stringVariablesContext);
runspace.AddCommandsFromLine("\"Hello, World!\" (S.$.var)");

runspace.Invoke(commandBlock);

Console.WriteLine(stringVariablesContext.Get("var")); // Output: Hello, World!