MVRScript

MVRScript is the essential base class for Virt-A-Mate plugin development. In Virt-A-Mate, every plugin must inherit from MVRScript because it provides the necessary infrastructure and integration with the core systems of the application.

  • Seamless Integration with VAM:
    MVRScript is designed to work in harmony with Virt-A-Mate. It automatically connects your plugin to the SuperController and other core VAM systems, ensuring consistent access to scene elements, atoms, and global settings.
  • Dynamic UI Management:
    MVRScript offers a rich set of helper methods to create, configure, and manage UI elements. Functions such as CreateButton, CreateSlider, and CreateToggle handle all aspects of UI instantiation, parenting, and synchronization. This standardization reduces the amount of boilerplate code in your plugin.
  • State Management with JSON:
    As a subclass of JSONStorable, MVRScript provides built-in support for storing and retrieving plugin data in JSON format. This feature ensures that settings and UI states persist across sessions without requiring additional implementation effort.
  • Centralized Access to Core Functionality:
    MVRScript wraps calls to the SuperController singleton. Methods for accessing scene atoms, controllers, and logging are provided out of the box, giving your plugin a consistent and reliable way to interact with the Virt-A-Mate environment.

Minimal MVRScript Template

This template is intended only to demonstrate how VAM organizes its core functionality. It serves as an educational reference for understanding the underlying design of Virt-A-Mate.

using UnityEngine;
using SimpleJSON;

public class MVRScript : JSONStorable
{
    // List for dynamic UI elements (e.g., left and right UI elements)

    // JSONStorable properties (e.g., enabled state, plugin label)

    // InitInternal: Initialize internal data structures and register JSON storables

    // InitUI: Setup and attach dynamic UI elements to UI containers

    // Awake: Called once at startup to perform initialization

    // Virtual Init: Override in your plugin for custom initialization
}

Important MVRScript Helper Methods

MVRScript provides a variety of helper methods that simplify working with atoms (scene objects), controllers, JSON storables, and UI elements in Virt-A-Mate. Below is a summary of some of the most commonly used methods and best practices.

Atom Access Helpers

  • GetContainingAtom()
    Returns the atom (scene object) that the script is attached to.
    Use Case: If you need to manipulate properties of the current atom in your plugin.

  • GetSceneAtoms()
    Returns a list of all atoms in the current scene.
    Use Case: Iterate over all scene objects.

  • GetAtomUIDs() / GetVisibleAtomUIDs()
    Return lists of UIDs (unique identifiers) for all atoms, or only those currently visible.
    Use Case: Identify which atoms are available or currently rendered.

  • GetAtomById(string uid)
    A convenience wrapper that first checks if SuperController.singleton exists, then retrieves an atom by its UID.

    Atom myAtom = GetAtomById("InvisibleLight");

    Note: “InvisibleLight” must match the atom’s actual UID in the scene.

Controller Helpers

  • GetMainController()
    Returns the main controller of the containing atom. Use Case: Often used for positioning, rotation, or camera alignment.
  • GetAllControllers()
    Returns an array of all controllers associated with the containing atom.
  • SelectController(FreeControllerV3 fc, bool alignView = false)
    Programmatically selects the specified controller. If alignView is true, the view aligns to that controller.

JSON (Save/Load) Helpers

  • SaveJSON(JSONClass jc, string saveName)
    Saves the provided JSON data (e.g., plugin settings) under the given saveName.
  • LoadJSON(string saveName)
    Loads previously saved JSON data by saveName.

UI Element Creation Helpers

MVRScript offers methods to quickly create UI controls (sliders, toggles, etc.) bound to JSONStorables:

  • CreateSlider(JSONStorableFloat jsf, bool rightSide = false)
    Instantiates a slider for a floating-point parameter. Usage:

    JSONStorableFloat myFloat = new JSONStorableFloat("MyFloat", 0f, null, 0f, 1f);
RegisterFloat(myFloat);
CreateSlider(myFloat, false);

  • CreateToggle(JSONStorableBool jsb, bool rightSide = false)
    Creates a checkbox (toggle) for a boolean parameter.

Other UI Creators

  • CreateColorPicker(JSONStorableColor jsc, bool rightSide = false)
  • CreateTextField(JSONStorableString jss, bool rightSide = false)
  • CreatePopup(JSONStorableStringChooser jsc, bool rightSide = false)
  • CreateButton(string label, bool rightSide = false)