FreeControllerV3

FreeControllerV3 is a core component in Virt-A-Mate that controls how objects (or “atoms”) move and rotate in your scene. It is built on Unity’s physics system and inherits from PhysicsSimulatorJSONStorable, which means it can simulate physics and save its state as JSON. In simpler terms, FreeControllerV3 is the engine behind an atom’s movement, rotation, and how it links to other objects.

Key Concepts and Features

Control States

FreeControllerV3 uses various control states to determine an atom’s behavior:

  • Position States: Define how the atom’s position is controlled. For example:

  • On / Off: Indicates whether the object’s position is being actively managed.

  • ParentLink / PhysicsLink: These states allow the object’s position to be driven by another object.

  • Rotation States: Similar to position states but for rotation. They decide whether the rotation is controlled directly or via a linked parent object.

Linking to Other Objects

One of the most powerful features of FreeControllerV3 is its ability to link an atom’s control to another’s. This means you can have one object follow the movement and rotation of another. The key method used for this is:

cubeControl.SelectLinkToRigidbody(sphereControlRB, FreeControllerV3.SelectLinkState.PositionAndRotation);

  • SelectLinkToRigidbody: This method links the Rigidbody (physics component) of one object’s control (e.g., the sphere) to another object’s control (e.g., the cube). Once linked, you can set the parent’s states so the target follows accordingly.

  • Setting the Link States: After linking, you adjust the parent’s control settings to make the link effective:

cubeControl.currentPositionState = FreeControllerV3.PositionState.ParentLink;
cubeControl.currentRotationState = FreeControllerV3.RotationState.ParentLink;

These settings ensure that the sphere’s position and rotation will follow the cube’s control.

UI Integration and JSON Storables

FreeControllerV3 automatically creates UI elements for adjusting parameters like position, rotation, and locking axes. It uses JSON storables to persist these settings, meaning your changes are saved with the scene. Even though there are many fields and methods, you only need to worry about the ones relevant to your task.

How to Use FreeControllerV3 in Your Projects

1. Retrieving the Controller

Each atom typically has a FreeControllerV3 component attached as its “control.” You can retrieve it like this:

FreeControllerV3 controller = atom.GetStorableByID("control") as FreeControllerV3;

2. Linking Two Objects

For example, to have a sphere follow a cube:

  • Get the Rigidbody component from the sphere’s control:
Rigidbody sphereControlRB = sphereControl.GetComponent<Rigidbody>();
  • Link the sphere to the cube:
cubeControl.SelectLinkToRigidbody(sphereControlRB, FreeControllerV3.SelectLinkState.PositionAndRotation);
cubeControl.currentPositionState = FreeControllerV3.PositionState.ParentLink;
cubeControl.currentRotationState = FreeControllerV3.RotationState.ParentLink;

This code sets up the parent–child relationship so that the sphere inherits both the position and rotation of the cube.

3. Adjusting Positions and Rotations Directly

FreeControllerV3 also provides methods for directly setting positions and rotations—both in world space and relative to the parent. This can be useful for snapping objects to specific locations or aligning them precisely.