Adds LightManager Actions and Classes

[winthos]

• Adds the GetLights action that serializes out all light game objects in a scene as a json of the class LightParameters

• Adds the SetLights action that takes serialized light object json and modifies a scene, allowing reconfiguration of lights by editing the json returned by GetLights. The flow of actions should always be GetLights first to serialize out what lights are in the scene and what can be changed.

• Adds the LightParameters serializable class. This is returned from actionReturn after calling GetLights in a scene.

  public class LightParameters {
      public string id { get; set; }
  
      public string type { get; set; }
  
      public Vector3 position { get; set; }
  
      public FlexibleRotation rotation;
  
      public bool enabled { get; set; }
  
      public string[] controllerSimObjIds { get; set; }
  
      public string parentSimObjObjectId { get; set; }
  
      public float spotAngle { get; set; }
  
      public float intensity { get; set; }
  
      public float range { get; set; }
  
      public SerializableColor rgb { get; set; }
  
      public float indirectMultiplier { get; set; }
  
      public string[] cullingMaskOff { get; set; }
  
      public ShadowParameters shadow = null;
  }

• Adds LightParameter compatibility with ProcTHOR house jsons. All ProcTHOR houses can now generate lights given the new properties exposed by the LightParameter class.

event = controller.step(action="GetLights")
event.metadata["actionReturn"]

Here is an example of a scene's light parameters returned via the GetLights action:

  {
    "id": "scene|Spot|0",
    "type": "Spot",
    "position": {
      "x": 0.029,
      "y": 2.489,
      "z": -1.734
    },
    "rotation": {
      "axis": {
        "x": 1.00000012,
        "y": 0.0,
        "z": 0.0
      },
      "degrees": 89.99999,
      "x": null,
      "y": null,
      "z": null
    },
    "enabled": true,
    "controllerSimObjIds": [
      "LightSwitch|+02.33|+01.31|-00.16"
    ],
    "parentSimObjObjectId": null,
    "spotAngle": 85.3615952,
    "intensity": 1.37,
    "range": 6.62,
    "rgb": {
      "r": 1.0,
      "g": 0.9133874,
      "b": 0.5514706,
      "a": 1.0
    },
    "indirectMultiplier": 1.0,
    "cullingMaskOff": [],
    "shadow": {
      "type": "Hard",
      "strength": 1.0,
      "normalBias": 0.4,
      "bias": 0.05,
      "nearPlane": 0.2,
      "resolution": "FromQualitySettings"
    }
  },
  {
    "id": "scene|Point|0",
    "type": "Point",
    "position": {
      "x": 0.852,
      "y": 1.091,
      "z": -0.891
    },
    "rotation": {
      "axis": {
        "x": 1.0,
        "y": 0.0,
        "z": 0.0
      },
      "degrees": 0.0,
      "x": null,
      "y": null,
      "z": null
    },
    "enabled": true,
    "controllerSimObjIds": null,
    "parentSimObjObjectId": null,
    "spotAngle": 0.0,
    "intensity": 0.66,
    "range": 3.0,
    "rgb": {
      "r": 0.75,
      "g": 0.9068965,
      "b": 1.0,
      "a": 1.0
    },
    "indirectMultiplier": 1.0,
    "cullingMaskOff": [],
    "shadow": {
      "type": "None",
      "strength": 1.0,
      "normalBias": 0.4,
      "bias": 0.05,
      "nearPlane": 0.2,
      "resolution": "FromQualitySettings"
    }
  },
  {
    "id": "scene|Spot|1",
    "type": "Spot",
    "position": {
      "x": 0.599999964,
      "y": 2.349,
      "z": -1.58099985
    },
    "rotation": {
      "axis": {
        "x": 1.00000012,
        "y": 0.0,
        "z": 0.0
      },
      "degrees": 89.99999,
      "x": null,
      "y": null,
      "z": null
    },
    "enabled": true,
    "controllerSimObjIds": [
      "LightSwitch|+02.33|+01.31|-00.16"
    ],
    "parentSimObjObjectId": null,
    "spotAngle": 74.0,
    "intensity": 1.0,
    "range": 5.0,
    "rgb": {
      "r": 1.0,
      "g": 0.910344839,
      "b": 0.75,
      "a": 1.0
    },
    "indirectMultiplier": 1.0,
    "cullingMaskOff": [],
    "shadow": {
      "type": "None",
      "strength": 1.0,
      "normalBias": 0.4,
      "bias": 0.05,
      "nearPlane": 0.2,
      "resolution": "FromQualitySettings"
    }
  }

Details of each LightParameter member

• id: string name of the light object's name in scene. This has a unique naming convention depending on if the light is a part of some sim object (ie: the light associated with a FloorLamp type object) or if the light simply exists on its own in the scene. Note that the instance of the light is part of the name, thus allowing you to determine if some sim object has multiple light sources associated with it, or if the scene itself has multiple instances of that type of light.

//light objects not associated with a sim object
scene|<Light Type>|<Light Instance>

//light objects that are children of some sim object
<SimObject.name>|<Light Type>|<Light Instance>

• type: The type of light as defined by Unity's light types . Valid types are Spot, Point, and Directional

• position: global (x, y, z) position of this light

• rotation: angle of this light in global space in angle-axis notation.

• enabled: boolean that determines if the light is enabled and emitting light or disabled

• controllerSimObjIds: a dict of sim object ids that control can control the enabled state of this light. These controller objects must be compatible with the ToggleOnOff action otherwise it cannot be used to control the active state of a light. Multiple controller objects can be assigned to a given light. This allows scene states where a single light can be turned on or off by multiple light switch objects, for exxample.

• parentSimObjObjectId: The object Id of the sim object this light is parented to. This allows the light to be positioned and linked with a sim object, and if that sim object is moved the light will move relative to its parent object. Only one parent object can be assigned at a time.

• spotAngle: The opening angle of a light that is of type Spot. Note that this does nothing if the light is not a spotlight. Valid range is [0-179]

• intensity: the light color is multiplied by this intensity value. The higher the brighter the light will be.

• range: The range in meters of the area the light can affect. This must be non-negative

• rgb: the color of the light in Red, Green, and Blue values. Each value must be in range [0, 1]. RGB values of [0, 255] should be converted to be compatible by dividing by 255 first.

• indirectMultiplier: the value of how much the light is multiplied when it bounces on a surface. This must be a non-negative value. 0 is no bounce, 1 is "normal" bounce, and anything greater than 1 is abnormally emissive.

• cullingMaskOff: An object will only be illuminated by a light if that light's cullingMask/ includes the layer chosen for the GameObject. Objects in Layers specified by cullingMaskOff will not be lit by this light.

• shadow: Includes various shadow properties for this light.

  "shadow": {
    "type": "Hard",
    "strength": 1.0,
    "normalBias": 0.4,
    "bias": 0.05,
    "nearPlane": 0.2,
    "resolution": "FromQualitySettings"
  }

• shadow["type"]: valid shadow types are None, Hard, and Soft which determine the types of edges created by shadows.

• shadow["strength"]: the intensity (how solid) of the shadow

• shadow["normalBias"]: allows offsetting the shadow's position relative to the normals of a surface

• shadow["bias"]: allows offsetting the shadow's position by manipulating the distance of the shadow map relative to what is casting the shadow.

• shadow["nearPlane]: defines the plane in which game objects do not cast shadows if close enough to the light

• shadow["resolution"] : selects the shadow resolution based on the available quality settings of the Unity instance

[winthos]

@mattdeitke I believe with the new syntax for light object naming, and the expanded LightParameters class, we may need to do something to update the ProcTHOR scenes right?

[Lucaweihs]

Closing this for now, may come back to it in the future.