Skip to main content

Intro to scripting with C#

Prepare environment​

C# scripting in the Massive Loop SDK is crucial for developing interactive and dynamic content. To get started, you'll need to install Visual Studio 2022 or Visual Studio 2019. The scripting experience is designed to be familiar to Unity developers, utilizing MonoBehavior components. The SDK also provides a comprehensive API for integrating Massive Loop systems and components seamlessly.

"Create project files"

The Massive Loop SDK uses the .proj files create by Visual Studio to find and catalog the scripts. Most of the times this is created by default when a new Unity Project started. In case this doesn't happen, you can create them by opening Edit/Preference in unity project, in External Tools, select either Visual Studio 2022 or Visual Studio 2019. then click on Regenerate project files

To select a world's scripting language, open SDK control panel, select world tab, select scripting and select CSharp option:

Selecting correct assembly definition​

To build and upload a World with C# scripting in the Massive Loop SDK, you need to select an Assembly Definition. Assembly Definitions are essential as they are used by Visual Studio to create .csproj files for your project. While the default "Assembly-CSharp" assembly definition is generally sufficient, it is recommended to create and select a separate assembly definition for each World, especially if you are using a single Unity project to upload multiple Worlds.

This approach helps in organizing your code better and ensures that each World has its own isolated environment, reducing the chances of conflicts and dependencies issues. For scripts that are common and need to be used across multiple Worlds, you can place them in their own assembly definition. You can then link this common assembly definition to the specific World assembly definitions as needed. This setup promotes modularity and reusability, making your development process more efficient and manageable.

Checkout this tutorial on how to use Assembly definition within the Unity Editor.

warning

For any world, a assembly definition must be selected. By default, the sdk select the default "Assembly-CSharp" definition which is created as the root assembly definition for the Unity Editor project. If no assembly definitions are visible on the list, make sure you have the Visual Studio 2022 or Visual Studio 2019 is installed, and follow the instructions above to generate project files.

Start scripting!​

You can add C# script by just creating a MonoBehaviour and attaching it to a gameobject in your scene!

If you are unfamiliar with scripting in Unity, we recommend check out this Scripting Manual provided by Unity.

Limitations​

Scripting in C# for the Massive Loop SDK involves certain limitations aimed at maintaining security, stability, and performance. These limitations can affect the namespaces, types, and methods you can use, as well as impose technical constraints on some systems. Here’s a detailed overview of these restrictions:

Security Restrictions on Namespaces, Types, and Methods:​

To ensure a secure environment, the following namespaces, types, and methods are restricted:

  • System.IO.*: Prevents direct file system access, which could otherwise compromise security.
  • System.Reflection.*: Restricts runtime type inspection and manipulation, which could be used to bypass security mechanisms.
  • System.Net.*: Limits network communication to avoid unauthorized data transfer.
  • UnityEditor.*: Ensures that editor-specific functionalities, which are not suitable for runtime, are not used.
  • UnityEngine.Networking.*: Controls network operations to maintain secure and stable networking within the platform.
  • System.AppDomain: Prevents manipulation of application domains, ensuring that the application's execution environment remains secure.
  • UnityEngine.Application: Restricts certain application-level operations that could affect the overall environment.
  • UnityEngine.SceneManagement.SceneManager: Controls scene loading and management to ensure stability.
  • UnityEngine.SceneManagement.SceneManagerAPI: Limits low-level scene management operations.
  • UnityEngine.SceneManagement.SceneUtility: Restricts utility functions related to scene management.
  • UnityEngine.AudioSettings: Controls audio configurations to prevent unauthorized changes.

Other types might also be unavailable to maintain a secure and consistent environment.

Generic Component Retrieval​

When scripting in C# in Massive Loop, you need to use the non-generic overloads of methods like AddComponent and GetComponent, or other component access methods. For example, instead of using gameObject.AddComponent<MyComponent>(), you should use gameObject.AddComponent(typeof(MyComponent)). Similarly, replace gameObject.GetComponent<MyComponent>() with gameObject.GetComponent(typeof(MyComponent)). This is required for proper binding of the user code with internal systems.

Known Technical Limitations:​

  • Cannot Serialize Unity Events: Serialization of Unity Events is not supported, which can affect how events are stored and transmitted.
  • Cannot Inherit from Some Internal Types, Specifically Generic Types: Inheritance from certain internal and generic types is limited.

Other Restrictions:​

  • Cannot Use Types from Managed or Native DLLs: To maintain a controlled and secure environment, types from external managed or native DLLs are not allowed.
  • P-Invoke is Not Allowed: Platform Invocation Services, which allow calling un-managed functions from managed code, are restricted to prevent unauthorized access to system-level resources.

These limitations are designed to create a secure, stable, and performant development environment within the Massive Loop platform. While they impose certain constraints, they are essential for ensuring the integrity and reliability of the overall system. Developers should be mindful of these restrictions and design their scripts accordingly to adhere to the platform’s guidelines.