3D and Materials: the light takes the documented settings

The public 3D and Materials panel options give the Light Settings as
Intensity (0–100 %), Rotation (-180° to 180°), Height (0° to 90°),
Softness (0–100 %) and Ambient Light (0–200 %), with the light moved to
the back or the front of the object. The 3D effects (Revolve included)
had Direction and Elevation (an azimuth and elevation), Intensity and
Ambient (0–100 %).

- Rotation turns the light round the object on the page (our reading:
  0° on its right, counterclockwise); Height raises it from beside the
  object (0°) to straight in front (90°); Light behind the object puts
  it at the back. The light gizmo's ring and line are Rotation and
  Height.
- Softness wraps the light round the object: at 0 % it falls off with
  the angle as before, at 100 % it reaches nothing only straight away.
- Ambient Light runs to 200 %; faces stay no brighter than the art.
- lightRotation, lightHeight, lightBehind and lightSoftness replace
  lightAzimuth and lightElevation. An earlier light is read as the same
  direction, so it shades exactly as before (old and new code give the
  same colours for the four effects and five lights); effect.setParams
  turns a stored one into the new form before applying new values, and
  the parameter description names lightAzimuth and lightElevation as the
  earlier form, so effect.apply and effect.setParams still take them. The
  default light is the earlier default's: Rotation 125.26°, Height 30°.
- The dialog's Lighting tab shows the settings in the documented order;
  Softness, Ambient Light and Light behind the object are in every
  catalog, and the unused Direction, Elevation and Ambient are gone.

Light colour, presets, several lights and shadows are not built.

crates/engine/src/cmd/effectcmd.rs

@@ -327,8 +327,8 @@ fn set_params(s: &mut Session, p: &Value) -> Result<Value> {
             if !cur.is_object() {
                 *cur = effects::merged_params(&e.id, &Value::Null);
             }
-            // Earlier parameters (a Perspective strength) take their current form first, so the
-            // new values replace them and the rest is kept.
+            // Earlier parameters (a Perspective strength, a light by azimuth and elevation) take
+            // their current form first, so the new values replace them and the rest is kept.
             *cur = effects::upgrade_params(&e.id, cur);
             if let Value::Object(m) = cur {
                 m.extend(new);
@@ -627,6 +627,26 @@ mod tests {
         assert_eq!(params(&s), json!({"depth": 50, "perspectiveAngle": 120}));
     }
 
+    /// Scripts from before Rotation and Height give the light by `lightAzimuth` and
+    /// `lightElevation`: stored as the same light; a later Height keeps that light's Rotation.
+    #[test]
+    fn an_earlier_light_direction_is_set_as_rotation_and_height() {
+        let (mut s, id) = session_with_rect();
+        s.execute(
+            "effect.apply",
+            &json!({"effect": effects::ROTATE, "ids": [id.0], "item": null, "params": {"lightAzimuth": 180, "lightElevation": 0}}),
+        )
+        .unwrap();
+        let params = |s: &Session| node(s, id).appearance.effects[0].params.clone();
+        // Straight from behind the object, level with it.
+        assert!(params(&s).get("lightAzimuth").is_none() && params(&s).get("lightElevation").is_none(), "{}", params(&s));
+        assert_eq!((params(&s)["lightHeight"].as_f64().unwrap().round(), &params(&s)["lightBehind"]), (90.0, &json!(true)));
+        std::sync::Arc::make_mut(&mut s.doc_mut().unwrap().doc).node_mut(id).unwrap().appearance.effects[0].params =
+            json!({"lightAzimuth": 90, "lightElevation": 0});
+        s.execute("effect.setParams", &json!({"index": 0, "params": {"lightHeight": 60}, "ids": [id.0], "item": null})).unwrap();
+        assert_eq!(params(&s), json!({"lightRotation": 0.0, "lightHeight": 60, "lightBehind": false}));
+    }
+
     fn effects_for_test(s: &Session, id: NodeId) -> vectorcraft_doc::Node {
         effects::revolve_art(&node(s, id)).unwrap()
     }