CraterCrashGH-610 Add in-editor script node documentation

CMakeLists.txt

@@ -59,13 +59,15 @@ INCLUDE(generate-license)
 INCLUDE(generate-version)
 INCLUDE(generate-donors)
 INCLUDE(godot-extension-db-generator)
+INCLUDE(godot-docs-generator)
 
 # Generation steps
 GENERATE_LICENSE()
 GENERATE_VERSION()
 GENERATE_AUTHORS()
 GENERATE_DONORS()
 GENERATE_GODOT_EXTENSION_DB()
+GENERATE_GODOT_DOCUMENTATION()
 
 # MacOS universal binary support
 IF (APPLE)
@@ -87,6 +89,8 @@ FILE(GLOB_RECURSE gdext_sources
         CONFIGURE_DEPENDS
         "${CMAKE_CURRENT_SOURCE_DIR}/src/*.[hc]"
         "${CMAKE_CURRENT_SOURCE_DIR}/src/*.[hc]pp"
+        # Includes the generated doc data from /doc_classes
+        "${CMAKE_BINARY_DIR}/_generated/*.cpp"
 )
 
 # GDExtension library

cmake/generate_godot_docs.py

@@ -0,0 +1,72 @@
+## This file is part of the Godot Orchestrator project.
+##
+## Copyright (c) 2023-present Vahera Studios LLC and its contributors.
+##
+## 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.
+##
+import os, sys, platform
+
+def make_doc_source(target, source):
+    import zlib
+
+    dst = str(target[0])
+    g = open(dst, "w", encoding="utf-8")
+    buf = ""
+    docbegin = ""
+    docend = ""
+    for src in source:
+        src_path = str(src)
+        if not src_path.endswith(".xml"):
+            continue
+        with open(src_path, "r", encoding="utf-8") as f:
+            content = f.read()
+        buf += content
+
+    buf = (docbegin + buf + docend).encode("utf-8")
+    decomp_size = len(buf)
+
+    # Use maximum zlib compression level to further reduce file size
+    # (at the cost of initial build times).
+    buf = zlib.compress(buf, zlib.Z_BEST_COMPRESSION)
+
+    g.write("/* THIS FILE IS GENERATED DO NOT EDIT */\n")
+    g.write("\n")
+    g.write("#include <godot_cpp/godot.hpp>\n")
+    g.write("\n")
+
+    g.write('static const char *_doc_data_hash = "' + str(hash(buf)) + '";\n')
+    g.write("static const int _doc_data_uncompressed_size = " + str(decomp_size) + ";\n")
+    g.write("static const int _doc_data_compressed_size = " + str(len(buf)) + ";\n")
+    g.write("static const unsigned char _doc_data_compressed[] = {\n")
+    for i in range(len(buf)):
+        g.write("\t" + str(buf[i]) + ",\n")
+    g.write("};\n")
+    g.write("\n")
+
+    g.write(
+        "static godot::internal::DocDataRegistration _doc_data_registration(_doc_data_hash, _doc_data_uncompressed_size, _doc_data_compressed_size, _doc_data_compressed);\n"
+    )
+    g.write("\n")
+
+    g.close()
+
+def main():
+    if len(sys.argv) > 2:
+        target_str = sys.argv[1]
+        target_list = target_str.split(",")
+        source_str = sys.argv[2]
+        source_list = source_str.split(",")
+        make_doc_source(target_list, source_list)
+
+if __name__ == "__main__":
+    main()

cmake/godot-docs-generator.cmake

@@ -0,0 +1,30 @@
+## This file is part of the Godot Orchestrator project.
+##
+## Copyright (c) 2023-present Vahera Studios LLC and its contributors.
+##
+## 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.
+##
+
+FUNCTION( GENERATE_GODOT_DOCUMENTATION )
+    # Grab all documentation XML files
+    FILE(GLOB XML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/doc_classes/*.xml")
+    STRING(JOIN "," XML_FILES_STR ${XML_FILES})
+    # Generate the target file
+    SET(DOC_DATA_CPP_FILE "${CMAKE_BINARY_DIR}/_generated/doc_data.cpp")
+    STRING(JOIN "," DOC_DATA_CPP_STR ${DOC_DATA_CPP_FILE})
+    # Run python to generate the doc_data.cpp file
+    EXECUTE_PROCESS(
+            COMMAND cmd /c py ${CMAKE_CURRENT_SOURCE_DIR}/cmake/generate_godot_docs.py ${DOC_DATA_CPP_STR} ${XML_FILES_STR}
+            WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    )
+ENDFUNCTION()

doc_classes/OScript.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScript" inherits="ScriptExtension" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        A script implementating the Orchestration visual script language.
+    </brief_description>
+    <description>
+        An [OScript] represents an orchestration, a graph-based, visual script language that works similarly to [GDScript].
+    </description>
+</class>

doc_classes/OScriptEditablePinNode.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptEditablePinNode" inherits="OScriptNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        An abstract node that enables an Orchestrator node to have editable input or output pins.
+    </brief_description>
+    <description>
+        Most Orchestrator nodes have a finite number of defined input and output pins based on what the node does. There are, however, use cases where it's helpful for a node to provide an unbounded number of input or output arguments.
+        For example, Godot provides a utility function called [method str].  This is a variable-argument method, meaning that the method accepts zero or more arguments to create a [code]String[/code] output.
+        [codeblock]
+        func _my_function():
+            var data1 = str("Hello", " ", "World")
+            var data2 = str("Hello", " ", 12345)
+        [/codeblock]
+        When a [OScriptNodeCallFunction] node is added to call [method str] in an Orchestration, you can add any number of input arguments due to the behavior provided by this node.
+        [b]Adding Inputs/Outputs:[/b][br]Use the [code]+[/code] button in the bottom-right corner to add new input/outputs.
+        [b]Removing Inputs/Outputs:[/b][br]Right-click the input/output pin's name and select [code]Remove Pin[/code] from the context-menu.
+    </description>
+</class>

doc_classes/OScriptNode.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNode" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        The base class for all Orchestrator nodes.
+    </brief_description>
+</class>

doc_classes/OScriptNodeArrayAddElement.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeArrayAddElement" inherits="OScriptNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Adds an element to an [Array].
+    </brief_description>
+    <description>
+        This node takes the [param target] pin [Array] and appends the specified [param element] pin item to the end of the array. The output [param index] pin returns the position in the [Array] where the item was added.
+    </description>
+</class>

doc_classes/OScriptNodeArrayAppend.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeArrayAppend" inherits="OScriptNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Appends one [Array] into another [Array].
+    </brief_description>
+    <description>
+        This node takes the [param target] [Array] and appends the contents of the [param source] [Array], returning the modified [param target] [Array] as the output.
+        [b]NOTE:[/b] The [param source] [Array] is not modified by this node, only the [param target] [Array].
+    </description>
+</class>

doc_classes/OScriptNodeArrayClear.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeArrayClear" inherits="OScriptNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Clears the contents of the given array.
+    </brief_description>
+    <description>
+        Removes all elements from the provided [Array].
+        The [param array] pin provides the [Array] instance that should be cleared. Once the array's elements have been cleared, the same [Array] instance is returned in the output [param array] pin.
+    </description>
+</class>

doc_classes/OScriptNodeArrayFind.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeArrayFind" inherits="OScriptNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Finds the specified element within the given array, returning its position.
+    </brief_description>
+    <description>
+        This node iterates each element in an [Array], locating the provided element. If it exists, the node returns the position within the [Array]. If the element does not exist, the node returns [code]-1[/code].
+        The [param array] pin specifies the [Array] that will be searched. The [param item] pin specifies the element item to find within the given array.
+        The output [param array] pin returns the input [Array] should additional operations need to be performed on the array. The output [param index] pin returns the index where the [param item] was found, or [code]-1[/code] if it was not found.
+    </description>
+</class>

doc_classes/OScriptNodeArrayGet.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeArrayGet" inherits="OScriptNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Get an element in an array by its index position.
+    </brief_description>
+    <description>
+        This node reads an element from a given [Array] at the specified position.
+        The [param Array] pin specifies the [Array] that will be read by this node. The [param index] pin specifies the position where the element will be read from. If the specified [param index] is out of bounds, meaning it is negative or greater-than or equal-to the size of the [Array], an error occurs.
+        The output [param element] pin provides the array element at the specified position as a [Variant].
+        [b]NOTE:[/b] An [OScriptNodeTypeCast] node can be used to access context-specific methods or properties on the element.
+    </description>
+</class>

doc_classes/OScriptNodeArrayRemoveElement.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeArrayRemoveElement" inherits="OScriptNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Removes an element from an [Array].
+    </brief_description>
+    <description>
+        This node attempts to remove the element specified by the [param element] pin from the [Array] specified by the [param target] pin. The [Array] is returned in the [param array] output pin regardless if the [param element] pin value is found and removed.
+        If the [Array] element is removed, the output [param removed] pin will be [code]true[/code], otherwise it will be [code]false[/code].
+    </description>
+</class>

doc_classes/OScriptNodeArrayRemoveIndex.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeArrayRemoveIndex" inherits="OScriptNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Removes an element from an [Array] by the specified index.
+    </brief_description>
+    <description>
+        This node attempts to remove the element at the position specified by the [param index] pin from the [Array] specified by the [param target] pin. The [Array] is returned in the [param array] output pin if the [param index] position is valid. If the [param index] is out of bounds, meaning negative or greater-than or equal-to the size of the [Array], an error occurs.
+    </description>
+</class>

doc_classes/OScriptNodeArraySet.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeArraySet" inherits="OScriptNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Set an element in an array by its index position.
+    </brief_description>
+    <description>
+        This node modifies an existing [Array] by adding the specified element into the [Array] at the given position.
+        The [param array] pin specifies the [Array] that will be modified by this node. The [param index] pin specifies the position within the array where the element is placed. The [param element] pin specifies the element value to be placed into the [Array].
+        If the [param index] position is outside the bounds of the array, the [param size_to_fit] pin can be used to control whether the provided [Array] will be automatically resized so that the write operation succeeds. If [param size_to_fit] is [code]false[/code] and the provided [param index] is out of bounds, an error will occur.
+        The output returns the modified [Array].
+    </description>
+</class>

doc_classes/OScriptNodeAssignLocalVariable.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeAssignLocalVariable" inherits="OScriptNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Assigns a value to a local variable.
+    </brief_description>
+    <description>
+        The [OScriptNodeAssignLocalVariable] node is used for assigning a value to a temporary local variable.
+        The [param variable] input pin should be connected with a [OScriptNodeLocalVariable] node, which specifies the variable that is to be assigned. The [param value] input pin specifies the value that should be assigned to the local variable.
+    </description>
+</class>

doc_classes/OScriptNodeAutoload.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeAutoload" inherits="OScriptNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Returns an instance of the specified autoload.
+    </brief_description>
+    <description>
+        An autoload in Godot is similar to a singleton, where there is only ever a singular instance of the object with the given name available. Autoloads are instrumental for providing access to common behavior and data within the scene.
+        The [OScriptNodeAutoload] node returns the autoload instance through the output pin. The specific autoload instance to return is specified by the [param autoload] property in the inspector. When looking for autoloads in the [param All Actions] window, autoloads are listed by their registered name.
+        To register an autoload, go to [b]Project > Project Settings[/b] and select the [b]Global[/b] tab. Under the subtab [b]Autoloads[/b], the specific autoload script can be registered with a unique name. Once registered, the autoload can be picked from the [OScriptNodeAutoload] node's inspector view or by searching for the autoload in the [param All Actions] window.
+    </description>
+    <tutorials>
+        <link title="Node reference">https://docs.cratercrash.com/orchestrator/nodes/autoloads</link>
+    </tutorials>
+</class>

doc_classes/OScriptNodeAwaitSignal.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeAwaitSignal" inherits="OScriptNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Yields execution of the orchestration until the specified [Signal] is raised.
+    </brief_description>
+    <description>
+        The [OScriptNodeAwaitSignal] node provides coroutine behavior to an orchestration.
+        The node accepts two key input values, the [param target] pin specifies the object that will fire the signal while the [param signal_name] specifies the name of the signal to wait for. When this node executes, it registers a callback for the specified signal, and yields execution back to Godot. Only once the signal is fired will the orchestration resume; otherwise it continues to wait for the signal to be raised.
+        This is quite useful if you need to submit a long-running task to a background thread without blocking the main engine loop. Once the background thread has completed the long-running task, it can schedule the signal to fire on the main thread, causing the orchestration to resume from where it left off.
+    </description>
+    <tutorials>
+        <link title="Node reference">https://docs.cratercrash.com/orchestrator/nodes/signals#await-a-signal</link>
+    </tutorials>
+</class>

doc_classes/OScriptNodeBranch.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeBranch" inherits="OScriptNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Conditionally branches execution flow based on a single condition.
+    </brief_description>
+    <description>
+        The [OScriptNodeBranch] provides a traditional if-else branch style operation. If the [param condition] is [code]true[/code], the node exits through the [param true] output pin, otherwise exits through the [param false] output pin.
+    </description>
+    <tutorials>
+        <link title="Node reference">https://docs.cratercrash.com/orchestrator/nodes/flow-control#branch</link>
+    </tutorials>
+</class>

doc_classes/OScriptNodeCallBuiltinFunction.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeCallBuiltinFunction" inherits="OScriptNodeCallFunction" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Executes a Godot built-in function.
+    </brief_description>
+    <description>
+        The [OScriptNodeCallBuiltinFunction] node is a specialized [OScriptNodeCallFunction] node that executes one of many Godot built-in functions such as [method str], [method print], and even [method floor]. Many of these functions are found under the [code]Utilities[/code] category in the [param All Actions] window.
+    </description>
+    <tutorials>
+        <link title="Node reference">https://docs.cratercrash.com/orchestrator/nodes/functions#built-in-functions</link>
+    </tutorials>
+</class>

doc_classes/OScriptNodeCallFunction.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeCallFunction" inherits="OScriptNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Abstract base class for all nodes that execute different function types.
+    </brief_description>
+</class>

doc_classes/OScriptNodeCallMemberFunction.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="OScriptNodeCallMemberFunction" inherits="OScriptNodeCallFunction" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+    <brief_description>
+        Executes a Godot class-specific function.
+    </brief_description>
+    <description>
+        The [OScriptNodeCallMemberFunction] node is a specialized [OScriptNodeCallFunction] node that executes one of many Godot functions that are member methods on classes, such as [method Vector3.abs] or [method InputEventKey.get_key_code].
+    </description>
+    <tutorials>
+        <link title="Node reference">https://docs.cratercrash.com/orchestrator/nodes/functions#calling-functions</link>
+    </tutorials>
+</class>