The Modular API

The Modular Assemblies Definition API (DefinitionApi from here on) is the beating heart of the framework. All communication between client mods and Modular Assemblies goes through it, and it offers several useful functions to ensure your custom assemblies work properly.

Installation

While the DefinitionApi is best used in the template, it can also be used standalone in your mods. The standalone installation guide can be found here. The template provides a simple project structure for using Modular Assemblies as the focus of your mod and will automatically handle loading your definitions, whereas the standalone DefinitionApi gives you more flexibility in using the framework exactly how your mod demands.

Updating

To update your version of the DefinitionApi, copy the entire latest API version into your existing DefinitionApi.cs file and check for broken references.

API Reference

All public methods are explained in the DefinitionApi's included documentation, but this reference will provide more details and give examples.

API Meta

Object	Description	Example
void Init(IMyModContext modContext, Action onLoad = null)	Prepares the DefinitionApi for use - this *must* be called before using the API. Include your mod context and an optional action to be triggered whenever the API fully loads (equivalent to OnReady).	DefinitionApi defApi = new DefinitionApi(); defApi.Init(this.ModContext);
int ApiVersion	The integer DefinitionApi version included in your mod. The latest API can always be [obtained from here.](https://github.com/StarCoreSE/Modular-Assemblies/blob/main/Data/Scripts/AssemblyScripts/Definitions/DefinitionApi.cs)	ShowNotification($"DefinitionApi {defApi.ApiVersion} loaded.");
int FrameworkVersion	The integer Modular Assemblies Framework version currently loaded.	ShowNotification($"Framework v{defApi.FrameworkVersion} detected.");
bool IsReady	Boolean value representing whether or not the DefinitionApi is ready for use.	public override void UpdateAfterSimulation() { if (!defApi.IsReady) return; // do stuff with the API }

Global Assembly Methods

Object	Description	Example
IMyCubeBlock[] GetAllParts()	Returns an array of all blocks in the world with AssemblyParts.	foreach (IMyCubeBlock block in defApi.GetAllParts()) { // Do stuff }
int[] GetAllAssemblies()	Returns an array of all PhysicalAssembly ids in the world..	ShowNotification($"{defApi.GetAllAssemblies().Count} assemblies registered.");

Per-Assembly Methods

Object	Description	Example
IMyCubeBlock[] GetMemberParts(int assemblyId)	Returns an array of all member blocks in a given assembly.	void RenameBlocksInAssembly(int assemblyId) { foreach (IMyCubeBlock block in defApi.GetMemberParts(assemblyId)) { block.DisplayNameText += $" [ASM {assemblyId}]"; } }
IMyCubeBlock GetBasePart(int assemblyId)	Returns the base part of a given assembly. If no base part is defined or the assembly does not exist, returns null.	long GetAssemblyOwner(int assemblyId) { IMyCubeBlock baseBlock = defApi.GetBasePart(assemblyId); return baseBlock.OwnerId; }
IMyCubeGrid GetAssemblyGrid(int assemblyId)	Returns the grid a given assembly is built on, or null if the assembly is not found.	defApi.GetAssemblyGrid(anAssemblyId)?.SetPosition(Vector3D.Zero);
void AddOnAssemblyClose(Action<int> action)	Registers an Action triggered on assembly removal. The action is run with the Assembly's ID as an argument.	defApi.AddOnAssemblyClose(AssemblyClosed); // elsewhere // This method will be triggered when an assembly is closed. void AssemblyClosed(int assemblyId) { ShowNotification($"Assembly {assemblyId} closed."); }
void RemoveOnAssemblyClose(Action<int> action)	Removes an Action triggered on assembly removal.	defApi.RemoveOnAssemblyClose(AssemblyClosed); // elsewhere // This won't be triggered anymore. void AssemblyClosed(int assemblyId) { ShowNotification($"Assembly {assemblyId} closed."); }
void RecreateAssembly(int assemblyId)	Removes all blocks from the assembly and queues them for a connection check. This will typically result in an identical assembly.	if (buttonPressed) { defApi.RecreateAssembly(anAssemblyId); }

Per-Part Methods

Object	Description	Example
IMyCubeBlock[] GetConnectedBlocks(IMyCubeBlock partBlockId, string definition, bool useCached = true)	Returns an array of parts connected to a given block. Use the `definition` parameter to select which definition name to check. Note - setting useCached to false will slightly improve performance, but can be unreliable when multithreading.	IMyCubeBlock[] neighborBlocks = defApi.GetConnectedBlocks(baseBlock, "Modular_Fusion");
int GetContainingAssembly(IMyCubeBlock blockPart, string definition)	Returns the ID of the assembly containing a given part, or -1 if no assembly was found. Use the `definition` parameter to select which definition name to check.	if (defApi.GetContainingAssembly(aBlock, "Modular_Fusion") != -1) { ShowNotification("The block is in an assembly!"); }
void RecreateConnections(IMyCubeBlock blockPart, string definition)	Removes a part from its assembly and queues it for a connection check. This can split assemblies temporarily, and often results in no net change.	if (defApi.GetContainingAssembly(aBlock, "Modular_Fusion") == -1) { ShowNotification("The block is not in an assembly!"); defApi.RecreateConnections(aBlock, "Modular_Fusion"); }