API for modders

If you want your mod activating blocks, but don't want to simulate key presses or write your own reflection code, you can use this API to do it through Lench Scripter Mod.

Your mod can interact with Lench Scripter Mod in three ways:

• Full
  If Lench Scripter Mod is installed and loaded, you can reference it's assembly and use all of it's functionality. This way you can extend what the user can do through Python scripts, use block handlers or implement your own.
• API-only
  If Lench Scripter Mod is installed without IronPython binaries and loaded by the mod loader, it runs in API-only mode. It will still initialize block handlers on simulation and you can still use them normally. Python engine will be unavailable. This is how Advanced Controls Mod uses it.
• Library
  If Lench Scripter Mod is not installed and loaded, you can use it as a library, meaning you have to call methods like InitializeBlockHandlers and CallUpdate by yourself.

Example use cases

• Control blocks
  Use Block handler objects to control blocks. These are the same objects that get passed to the Python script.

  Piston p = BlockHandlers.GetBlock(myBlockBehaviour) as Piston;
  p.Extend();
  p.SetPosition(0.5f);
  
  Steering s = BlockHandlers.GetBlock(otherBlockBehav) as Steering;
  s.SetAngle(23);

• Implement your own block handlers
  Extend the functionality of the scripting mod by implementing your own block handlers.

  // Extend BlockHandler class to create a custom block handler.
  class MyBlock : BlockHandler
  {
      MyBlock(BlockBehaviour bb) : base(bb)
      {
          // initialisation code
      }
  
      void DoStuff()
      {
          Debug.Log("my block did stuff");
      }
  }
  
  // Add it as a block handler for a new BlockHandler type,
  // or replace an existing one before simulation starts.
  BlockHandlers.AddBlockHandler(123, typeof(MyBlock));
  // Mod will now create MyBlock object for every block of type 123.
  
  // Use it during simulation.
  MyBlock b = BlockHandlers.GetBlock(someBlockBehav) as MyBlock;
  b.DoStuff();

  See block handlers source code for more information on the base class.

• Access Mod's script scope
  You can access the mod's Python environment to access the users' script scope.

  // Environment used by the scripting mod
  var python = PythonEnvironment.ScripterEnvironment;
  var value = python.GetVariable<float>("some_variable");
  
  // Exception handling and Python-style exception formatting
  try
  {
      object result = python.Execute("1 / 0");
      Debug.Log(Convert.ToSingle(result));
  }
  catch (Exception e)
  {
      Debug.Log("Error:");
      Debug.Log(PythonEnvironment.FormatException(e));
  }

• Create your own Python environment
  You can create your own and separate environment for running your Python code.

  var python = PythonEnvironment();
  
  python.SetVariable("x", 3);
  
  // Instead of calling Execute, you can compile any Python code to a Func<object>.
  // Use this if you're executing the same code many times.
  var myfunc = python.Compile("1 + 2 + x");
  var result = myfunc.Invoke();

Documentation

BlockHandlers

Contains all BlockHandler related functionality. Use this to manipulate blocks or implement your own block handlers.

Members	Description
AddBlockHandler (int BlockType, Type BlockHandler)	Add custom BlockHandler to be initialized for blocks of BlockType. Must derive from Block base class. Custom Block handlers need to be set before they are initialized.
InitializeBlockHandlers()	Initializes BlockHandler objects for every block in the machine. Is called automatically at the start of the simulation if scripting mod is loaded, otherwise you need to call it yourself.
DestroyBlockHandlers()	Clears the dictionary with references to the Block handlers. Is called automatically at the end of the simulation if scripting mod is loaded, otherwise you need to call it yourself.
GetBlock (BlockBehaviour bb)	Returns BlockHandler for a given BlockBehaviour object.
GetBlock (Guid guid)	Returns BlockHandler for a block with given Guid.
GetBlock (String id)	Returns BlockHandler for a block with given sequential identifier.
GetBlocks()	Returns a List of all initialized Block handlers.
GetID (GenericBlock block)	Returns sequential identifier of a block during building.
GetID (Guid guid)	Returns sequential identifier of a block during building.

PythonEnvironment

Represents a Python script scope with imported CLR modules. All scripting mod interaction with Python is done through this module.

Members	Description
Enabled	Is script enabled to be ran on simulation start.
Loaded	Are Python assemblies loaded and engine ready to be initialised.
ScripterEnvironment	Main PythonEnvironment instance used by the scripting mod.
CallUpdate()	CallsPython Update function.
CallFixedUpdate()	Calls Python FixedUpdate function.
Compile(String code)	Compiles code into a function that is run in current scope.
Execute(String expression)	Executes Python expression.
LoadCode(String code)	Compiles and executes code from string. Checks for Update and FixedUpdate functions.
LoadScript(String path)	Compiles and executes code from file. Checks for Update and FixedUpdate functions.
ContainsVariable(String name)	Returns true if the current scope contains variable with given name.
GetVariable(String name)	Returns value of the variable with given name in the current scope.
GetVariable<T>(String name)	Returns value of the variable with given name in the current scope as type T.
static InitializeEngine()	Initializes IronPython engine. Is called by constructor if not currently initialised.
static DestroyEngine()	Destroys IronPython engine.
static AddInitStatement(String s)	Adds a Python statement to list of initialisation statements, that are run for every environment initialised. Use this to import your modules and set the environment.
static FormatException(Exception e)	Formats given exception to Python style.