Plugin scripting

Assets/Editor/BrushLister.cs

@@ -85,7 +85,15 @@ public static string getBrushRowString(BrushDescriptor brush, bool experimental)
             {
                 manifest = "Experimental";
             }
-            return $"{brush.Description}\t{brush.m_AudioReactive}\t{prefabName}\t{materialName}\t{shaderName}\t{brushScripts}\t{experimental}\t{brush.m_SupersededBy}\t{manifest}";
+
+            string semantics = "";
+            if (brush.m_BrushPrefab != null)
+            {
+                var script = brush.m_BrushPrefab.GetComponentInChildren<BaseBrushScript>();
+                var layout = script.GetVertexLayout(brush);
+                semantics = $"{layout.texcoord0.semantic}\t{layout.texcoord1.semantic}\t{layout.texcoord2.semantic}";
+            }
+            return $"{brush.m_DurableName}\t{brush.m_AudioReactive}\t{prefabName}\t{materialName}\t{shaderName}\t{brushScripts}\t{experimental}\t{brush.m_SupersededBy}\t{manifest}\t{semantics}";
         }
 
         public static string sniffBrushScript(BrushDescriptor brush)

Assets/Editor/LuaAssetImporter.cs

@@ -0,0 +1,15 @@
+using System.IO;
+using UnityEditor.AssetImporters;
+using UnityEngine;
+
+[ScriptedImporter(1, "lua")]
+public class LuaAssetImporter : ScriptedImporter
+{
+    // Allow loading of .lua files as TextAssets
+    public override void OnImportAsset(AssetImportContext ctx)
+    {
+        TextAsset subAsset = new TextAsset(File.ReadAllText(ctx.assetPath));
+        ctx.AddObjectToAsset("text", subAsset);
+        ctx.SetMainObject(subAsset);
+    }
+}

Assets/Editor/LuaDocsGenerator.cs

@@ -0,0 +1,127 @@
+// Copyright 2023 The Tilt Brush Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System.Collections.Generic;
+using System.IO;
+using System.Text;
+using MoonSharp.Interpreter;
+using UnityEditor;
+using UnityEngine;
+
+namespace TiltBrush
+{
+
+    public class LuaDocsGenerator : Editor
+    {
+        [MenuItem("Open Brush/API/Generate Lua Docs")]
+        static void GenerateDocs()
+        {
+            if (!Application.isPlaying)
+            {
+                Debug.LogError("You can only run this whilst in Play Mode");
+                return;
+            }
+
+            Script script = new Script();
+
+            // Initializing this list triggers the docs generation via RegisterApiClasses
+            LuaDocsRegistration.ApiDocClasses = new List<LuaDocsClass>();
+            LuaManager.Instance.RegisterApiClasses(script);
+
+            // List wrappers aren't places in the script's namespace but we do want to register them
+            // so we can generate docs for them.
+            LuaDocsRegistration.RegisterForDocs(typeof(CameraPathListApiWrapper), false);
+            LuaDocsRegistration.RegisterForDocs(typeof(EnvironmentListApiWrapper), false);
+            LuaDocsRegistration.RegisterForDocs(typeof(GuideListApiWrapper), false);
+            LuaDocsRegistration.RegisterForDocs(typeof(ImageListApiWrapper), false);
+            LuaDocsRegistration.RegisterForDocs(typeof(LayerListApiWrapper), false);
+            LuaDocsRegistration.RegisterForDocs(typeof(ModelListApiWrapper), false);
+            LuaDocsRegistration.RegisterForDocs(typeof(VideoListApiWrapper), false);
+            LuaDocsRegistration.RegisterForDocs(typeof(StrokeListApiWrapper), false);
+
+            // Manually add some entries that aren't added the standard way
+            var transformProp = new LuaDocsType { PrimitiveType = LuaDocsPrimitiveType.UserData, CustomTypeName = "Transform" };
+            var vector3Prop = new LuaDocsType { PrimitiveType = LuaDocsPrimitiveType.UserData, CustomTypeName = "Vector3" };
+            var rotationProp = new LuaDocsType { PrimitiveType = LuaDocsPrimitiveType.UserData, CustomTypeName = "Rotation" };
+            var toolApiDocClass = new LuaDocsClass
+            {
+                Name = "Tool",
+                Methods = new List<LuaDocsMethod>(),
+                EnumValues = new List<LuaDocsEnumValue>(),
+                Description = "A class to interact with Scripted Tools",
+                IsTopLevelClass = true,
+                Properties = new List<LuaDocsProperty>
+                {
+                    new() {Name=LuaNames.ToolScriptStartPoint, PropertyType = transformProp, Description = "The position and orientation of the point where the trigger was pressed"},
+                    new() {Name=LuaNames.ToolScriptEndPoint, PropertyType = transformProp, Description = "The position and orientation of the point where the trigger was released"},
+                    new() {Name=LuaNames.ToolScriptVector, PropertyType = vector3Prop, Description = "The vector from startPoint to endPoint"},
+                    new() {Name=LuaNames.ToolScriptRotation, PropertyType = rotationProp, Description = "The rotation from startPoint to endPoint"},
+                }
+            };
+            LuaDocsRegistration.ApiDocClasses.Add(toolApiDocClass);
+
+            // JSON docs if needed
+            // var json = JsonConvert.SerializeObject(LuaDocsRegistration.ApiDocClasses, Formatting.Indented);
+            // File.WriteAllText(Path.Join(docsPath, "docs.json"), json);
+
+            // Generate __autocomplete.lua
+            var autocomplete = new StringBuilder();
+            autocomplete.Append("---@meta\n\n");
+            string autocompleteFilePath = Path.Combine("Assets/Resources/LuaModules", "__autocomplete.lua");
+            foreach (var klass in LuaDocsRegistration.ApiDocClasses)
+            {
+                // Only top level classes are included in autocomplete
+                // This excludes all ListWrapper classes which can't be instantiated directly
+                // And don't have any useful static members
+                if (!klass.IsTopLevelClass) continue;
+                autocomplete.Append(klass.AutocompleteSerialize());
+            }
+
+            // Some hardcoded Moonsharp built-ins
+            autocomplete.Append(@"
+---@class json
+json = {}
+---@param jsonString string The JSON string to parse
+---@return table # A table representing the parsed JSON
+function json:parse(jsonString) end
+
+---@param table table The table to serialize to JSON
+---@return string # The JSON representation of the table
+function json:serialize(table) end
+
+---@return jsonNull # a special value which is a representation of a null in JSON
+function json:null() end
+
+---@return bool # true if the value specified is a null read from JSON
+function json:isNull() end
+");
+
+            File.WriteAllText(autocompleteFilePath, autocomplete.ToString());
+            LuaManager.Instance.CopyLuaModules(); // Update the copy in User docs (also done on app start)
+
+            // Generate markdown docs
+            string docsPath = Path.Join(LuaManager.Instance.UserPluginsPath(), "LuaDocs");
+            if (!Directory.Exists(docsPath)) Directory.CreateDirectory(docsPath);
+            foreach (var klass in LuaDocsRegistration.ApiDocClasses)
+            {
+                var markDown = klass.MarkdownSerialize();
+                File.WriteAllText(Path.Join(docsPath, $"{klass.Name.ToLower()}.md"), markDown);
+            }
+
+            // Done
+            LuaDocsRegistration.ApiDocClasses = null;
+            Debug.Log($"Finished Generating Lua Docs");
+        }
+    }
+}

Assets/Editor/LuaExampleScriptsTest.cs

@@ -0,0 +1,176 @@
+// Copyright 2023 The Tilt Brush Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System;
+using System.Linq;
+using MoonSharp.Interpreter;
+using UnityEditor;
+using UnityEngine;
+
+namespace TiltBrush
+{
+
+    // Attempts to call all known functions on all scripts.
+    // Currently lots of false positives because we aren't calling the script as it's usually called.
+    // But still a useful smoke test for syntax errors and name changes.
+    public class LuaExampleScriptsTest : Editor
+    {
+        public static DynValue CallFunctionIfExists(Script script, string fnName)
+        {
+            var fn = script.Globals.Get(fnName).Function;
+            if (fn != null)
+            {
+                try
+                {
+                    return script.Call(fn);
+                }
+                catch (InterpreterException e)
+                {
+                    string msg = e.DecoratedMessage ?? e.Message;
+                    msg = LuaManager.ReformatLuaError(script, fnName, msg);
+                    Debug.LogError(msg);
+                }
+                catch (Exception e)
+                {
+                    string msg = e.Message;
+                    msg = LuaManager.ReformatLuaError(script, fnName, msg);
+                    Debug.LogError(msg);
+                }
+            }
+            return null;
+        }
+
+        [MenuItem("Open Brush/API/Test Example Scripts")]
+        static void DoTest()
+        {
+            if (!Application.isPlaying)
+            {
+                Debug.LogError("You can only run this whilst in Play Mode");
+                return;
+            }
+
+            var pointerScripts = LuaManager.Instance.Scripts[LuaApiCategory.PointerScript];
+            var symmetryScripts = LuaManager.Instance.Scripts[LuaApiCategory.SymmetryScript];
+            var toolScripts = LuaManager.Instance.Scripts[LuaApiCategory.ToolScript];
+            var backgroundScripts = LuaManager.Instance.Scripts[LuaApiCategory.BackgroundScript];
+
+            foreach (var example in pointerScripts)
+            {
+                var script = example.Value;
+                TestAllKnown(script);
+            }
+
+            foreach (var example in symmetryScripts)
+            {
+                var script = example.Value;
+                TestAllKnown(script);
+            }
+
+            foreach (var example in toolScripts)
+            {
+                var script = example.Value;
+                LuaManager.Instance.SetApiProperty(script, $"Tool.{LuaNames.ToolScriptVector}", Vector3.one);
+                LuaManager.Instance.SetApiProperty(script, $"Tool.{LuaNames.ToolScriptRotation}", Quaternion.LookRotation(Vector3.one));
+                TestAllKnown(script);
+            }
+
+            foreach (var example in backgroundScripts)
+            {
+                var script = example.Value;
+                TestAllKnown(script);
+            }
+
+            void TestAllKnown(Script script)
+            {
+                LuaManager.Instance.InitScript(script);
+                DynValue result;
+                result = CallFunctionIfExists(script, LuaNames.Start);
+                result = CallFunctionIfExists(script, LuaNames.Main);
+                result = CallFunctionIfExists(script, LuaNames.End);
+            }
+        }
+    }
+
+    public class TestSpecificScript : EditorWindow
+    {
+        private int selectedIndex = 0;
+        private string inputText = "";
+
+        [MenuItem("Open Brush/API/Test Specific Script")]
+        static void Init()
+        {
+            if (!Application.isPlaying)
+            {
+                Debug.LogError("You can only run this whilst in Play Mode");
+                return;
+            }
+            TestSpecificScript window = (TestSpecificScript)GetWindow(typeof(TestSpecificScript));
+            window.Show();
+        }
+
+        void OnGUI()
+        {
+            if (!Application.isPlaying) return;
+
+            EditorGUILayout.BeginVertical();
+
+            string[] scriptNames = LuaManager.Instance.GetScriptNames(LuaApiCategory.ToolScript).ToArray();
+            selectedIndex = EditorGUILayout.Popup("Dropdown", selectedIndex, scriptNames);
+
+            if (GUILayout.Button("Submit"))
+            {
+                SubmitDropDownValue(scriptNames[selectedIndex]);
+            }
+
+            inputText = EditorGUILayout.TextField("Input Text", inputText);
+
+            if (Event.current.type == EventType.KeyDown
+                && Event.current.keyCode == KeyCode.Return
+                && GUI.GetNameOfFocusedControl() == "TextField")
+            {
+                SubmitTextValue(inputText);
+                Event.current.Use(); // Consume this event, we don't want to trigger other behavior with return key.
+            }
+
+            if (GUILayout.Button("Submit Text"))
+            {
+                SubmitTextValue(inputText);
+            }
+
+            EditorGUILayout.EndVertical();
+        }
+
+        void SubmitTextValue(string cmd)
+        {
+            Script script = new Script();
+            LuaManager.Instance.InitScriptOnce(script);
+            var result = script.DoString($"return {cmd}");
+            Debug.Log(result);
+        }
+
+        void SubmitDropDownValue(string value)
+        {
+            var script = LuaManager.Instance.Scripts[LuaApiCategory.ToolScript][value];
+            SketchSurfacePanel.m_Instance.EnableSpecificTool(BaseTool.ToolType.ScriptedTool);
+            LuaManager.Instance.SetActiveScriptByName(LuaApiCategory.ToolScript, value);
+
+            var startPoint = Vector3.up;
+            var endPoint = Vector3.up + Vector3.one;
+            LuaManager.Instance.SetApiProperty(script, $"Tool.{LuaNames.ToolScriptVector}", endPoint - startPoint);
+            LuaManager.Instance.SetApiProperty(script, $"Tool.{LuaNames.ToolScriptRotation}", Quaternion.LookRotation(endPoint - startPoint));
+            LuaManager.Instance.DoToolScript(LuaNames.Main, TrTransform.T(startPoint), TrTransform.T(endPoint));
+        }
+    }
+
+}