Improve signal syntax (#700)

* Improve signal syntax for Kotlin and Java

---------

Co-authored-by: chippmann <cedric.hippmann@hotmail.com>

Author: CedNaru

docs/src/doc/user-guide/signals.md

@@ -1,22 +1,26 @@
-To create a signal use the delegate function `signal` and annotate it with `@RegisterSignal`.
+Signals in Godot are typed generic classes. They must be connected to and emitted using those exact arguments as well.
+You have 2 ways to declare your custom signals in scripts: Using a delegate or a backing field.
 
-!!! warning Signal parameter count
-    In GDScript, signals can have any number of arguments, this is not possible in Kotlin as it is a statically typed language. At the moment, you can create signals and expose them to Godot with at most 10 parameters.  
-    If you need more than 10 parameters, you can either use the not typesafe function `connect(signalAsString, targetObject, targetMethodAsString)` and the corresponding emit function or you can write your own typesafe extension functions like we did, to further increase the supported arg count. Keep in mind that you pass in the converted function and signal names (`snake_case`) to the above mentioned functions (see the section [Naming](#naming) below for details).
+The delegate is the recommended way, it is lightweight and doesn't store the signal directly, instead it generates a new one each call.
+You can opt to directly create a signal and store it in your script, but it uses more memory.
+Signals are not stateful so it's usually a waste to store them directly per instance, unless you have a high rate of connection/disconnection.
 
+In both case, you have to provide the name of the signal parameters as strings for the registration to Godot.
 
 ```kotlin
 @RegisterClass
-class RotatingCube: Node3D() {
+class MyScript: Node() {
+    @RegisterSignal
+    val mySignal by signal1<Boolean>("reverse")
+    
     @RegisterSignal
-    val reverseChanged: Signal1<Boolean> by signal("reverse")
+    val mySignal = Signal1<Boolean>("mySignal", "reverse")
 }
 ```
 
-## Naming
-
-For consistency with Godot's style, the name of your signal is converted to snake_case.
-The signal `helloThere` is known as `hello_there` in GDScript.
+!!! warning Signal parameter count
+    In GDScript, signals can have any number of arguments, this is not possible in Kotlin as it is a statically typed language. 
+    At the moment, you can create signals and expose them to Godot up to 16 parameters.
 
 ## Emitting
 
@@ -44,7 +48,20 @@ class AnotherObject: Object() {
     val targetObject = SomeObject()
 
     init {
-        reverseChanged.connect(targetObject, targetObject::onReverseChanged)
+        mySignal.connect(targetObject, targetObject::onReverseChanged)
     }
 }
 ```
+
+You can also use Kotlin lambdas directly to subscribe to signals
+
+```kt
+mySignal.connect {
+    println("This message has been written by a Kotlin Lambda")
+}
+```
+
+## Naming
+
+For consistency with Godot's style, the name of your signal is converted to snake_case.
+The signal `helloThere` is known as `hello_there` in GDScript.

harness/tests/src/main/java/godot/tests/JavaTestClass.java

@@ -9,10 +9,10 @@
 @RegisterClass
 public class JavaTestClass extends Node {
     @RegisterSignal
-    public Signal testSignal = SignalProvider.signal(this, "test_signal");
+    public Signal0 testSignal = Signal0.create(this, "test_signal");
 
     @RegisterSignal
-    public Signal2<String, String> testSignal2 = SignalProvider.signal(this, "test_signal_2", "param1", "param2");
+    public Signal2<String, String> testSignal2 = Signal2.create(this, "test_signal_2", "param1", "param2");
 
     // The following should NOT work as we cannot extract parameter names. The compiler checks should catch that and throw a build error
 //    @RegisterSignal

harness/tests/src/main/kotlin/godot/tests/FuncRefTest.kt

@@ -6,15 +6,15 @@ import godot.annotation.RegisterFunction
 import godot.annotation.RegisterProperty
 import godot.annotation.RegisterSignal
 import godot.annotation.Rpc
-import godot.core.signal
+import godot.core.signal0
 import godot.extensions.call
 import godot.extensions.callDeferred
 
 @RegisterClass
 class FuncRefTest : Node() {
 
     @RegisterSignal
-    val test by signal()
+    val test by signal0()
 
     @RegisterProperty
     var blubb: Boolean = false

harness/tests/src/main/kotlin/godot/tests/Invocation.kt

@@ -22,7 +22,6 @@ import godot.annotation.PlaceHolderText
 import godot.annotation.RegisterClass
 import godot.annotation.RegisterFunction
 import godot.annotation.RegisterProperty
-import godot.annotation.RegisterSignal
 import godot.core.Color
 import godot.core.Dictionary
 import godot.core.NodePath
@@ -34,15 +33,10 @@ import godot.core.PackedStringArray
 import godot.core.PackedVector2Array
 import godot.core.PackedVector3Array
 import godot.core.RID
-import godot.core.Signal1
-import godot.core.Signal2
 import godot.core.VariantArray
 import godot.core.Vector2
 import godot.core.Vector3
-import godot.core.asStringName
-import godot.core.connect
 import godot.core.dictionaryOf
-import godot.core.signal
 import godot.core.variantArrayOf
 import godot.extensions.getNodeAs
 import godot.registration.Range
@@ -319,38 +313,6 @@ class Invocation : Node3D() {
     @RegisterProperty
     var utf8String = ""
 
-    @RegisterSignal
-    val noParam by signal()
-
-    @RegisterSignal
-    val oneParam: Signal1<Boolean> by signal("refresh")
-
-    @RegisterSignal
-    val twoParam: Signal2<String, Invocation> by signal("str", "inv")
-
-    @RegisterSignal
-    val signalWithMultipleTargets: Signal1<Vector2> by signal("vector2")
-
-    //To store values emitted by signals
-    @RegisterProperty
-    var array: VariantArray<Vector2> = VariantArray()
-
-    @RegisterFunction
-    fun targetFunctionOne(vector2: Vector2) {
-        array.append(vector2)
-        //call GodotAPI to insert different parameters in the stack.
-        this.setMeta("Random".asStringName(), "Value")
-        val size = array.size
-        if (size < 8)
-        //Call signal inside another signal
-            signalWithMultipleTargets.emit(Vector2(1, size))
-    }
-
-    @RegisterFunction
-    fun targetFunctionTwo(vector2: Vector2) {
-        array.append(vector2)
-    }
-
     @RegisterFunction
     fun intValue(value: Int) = value
 
@@ -408,34 +370,17 @@ class Invocation : Node3D() {
         val path = NodePath("CanvasLayer/Button")
         val getNode2 = getNodeAs<Button>(path)
 
-        noParam.connect(invocation, OtherScript::hookNoParam)
-        oneParam.connect(invocation, OtherScript::hookOneParam)
-        twoParam.connect(invocation, OtherScript::hookTwoParam)
-
-        noParam.connect { println("noParam signal emitted") }
-        oneParam.connect { b -> println("oneParam signal emitted with $b") }
-        twoParam.connect { p0, p1 -> println("twoParam signal emitted with $p0 and $p1") }
-
-        signalWithMultipleTargets.connect(this, Invocation::targetFunctionOne)
-        signalWithMultipleTargets.connect(this, Invocation::targetFunctionTwo)
-
         (getNodeOrNull(path) as Button?)?.pressed?.connect(
             invocation,
             OtherScript::hookNoParam
         )
-        noParam.emit()
-        oneParam.emit(false)
-        twoParam.emit("My Awesome param !", this)
-
-        signalWithMultipleTargets.emit(Vector2(0, 0))
 
         println("NavMesh instance id before re-assign: ${resourceTest.getInstanceId()}")
         resourceTest = NavigationMesh()
         println("NavMesh instance id after re-assign: ${resourceTest.getInstanceId()}")
         resourceTest = NavigationMesh()
         println("NavMesh instance id after re-re-assign: ${resourceTest.getInstanceId()}")
 
-
         //Just there to register static instances in the GC
         GodotStaticDelegateTest.myScene
         GodotStaticDelegateTest.ref

harness/tests/src/main/kotlin/godot/tests/LambdaCallableTest.kt

@@ -8,19 +8,20 @@ import godot.annotation.RegisterSignal
 import godot.core.Signal3
 import godot.core.asCallable
 import godot.core.connect
-import godot.core.signal
+import godot.core.signal0
+import godot.core.signal3
 
 @RegisterClass
 class LambdaCallableTest : Node() {
 
     @RegisterSignal
-    val signalNoParam by signal()
+    val signalNoParam by signal0()
 
     @RegisterProperty
     var hasSignalNoParamBeenTriggered = false
 
     @RegisterSignal
-    val signalWithParams: Signal3<String, Long, Node> by signal("str", "long", "node")
+    val signalWithParams: Signal3<String, Long, Node> by signal3("str", "long", "node")
 
     @RegisterProperty
     var signalString: String = ""

harness/tests/src/main/kotlin/godot/tests/coroutine/CoroutineTest.kt

@@ -6,10 +6,10 @@ import godot.annotation.RegisterClass
 import godot.annotation.RegisterFunction
 import godot.annotation.RegisterProperty
 import godot.annotation.RegisterSignal
-import godot.core.Signal1
-import godot.core.Signal4
 import godot.core.Vector2
-import godot.core.signal
+import godot.core.signal0
+import godot.core.signal1
+import godot.core.signal4
 import godot.coroutines.GodotCoroutine
 import godot.coroutines.await
 import kotlinx.coroutines.CoroutineStart
@@ -18,13 +18,13 @@ import kotlinx.coroutines.CoroutineStart
 class CoroutineTest : Object() {
 
     @RegisterSignal
-    val signalWithoutParameter by signal()
+    val signalWithoutParameter by signal0()
 
     @RegisterSignal
-    val signalWithOneParameter: Signal1<Int> by signal("int")
+    val signalWithOneParameter by signal1<Int>("int")
 
     @RegisterSignal
-    val signalWithManyParameters: Signal4<Int, Float, Vector2, String> by signal("int", "float", "vector2", "string")
+    val signalWithManyParameters by signal4<Int, Float, Vector2, String>("int", "float", "vector2", "string")
 
     @RegisterProperty
     var step: Int = 0

harness/tests/src/main/kotlin/godot/tests/inheritance/AbstractClassInheritanceChild.kt

@@ -4,14 +4,13 @@ import godot.annotation.RegisterClass
 import godot.annotation.RegisterFunction
 import godot.annotation.RegisterProperty
 import godot.annotation.RegisterSignal
-import godot.core.Signal2
-import godot.core.signal
+import godot.core.signal2
 
 @RegisterClass
 class AbstractClassInheritanceChild : AbstractClassInheritanceParent() {
 
     @RegisterSignal
-    override val testOverridden: Signal2<String, Int> by signal("blubb", "habbalubbb")
+    override val testOverridden by signal2<String, Int>("blubb", "habbalubbb")
 
     //---------------- Here to check ------------------
 

harness/tests/src/main/kotlin/godot/tests/inheritance/AbstractClassInheritanceParent.kt

@@ -5,9 +5,8 @@ import godot.annotation.Export
 import godot.annotation.RegisterFunction
 import godot.annotation.RegisterProperty
 import godot.annotation.RegisterSignal
-import godot.core.Signal1
-import godot.core.Signal2
-import godot.core.signal
+import godot.core.signal1
+import godot.core.signal2
 
 // register class annotation is optional for abstract classes
 abstract class AbstractClassInheritanceParent : Node() {
@@ -17,10 +16,10 @@ abstract class AbstractClassInheritanceParent : Node() {
     var registeredExportedPropertyInParent = false
 
     @RegisterSignal
-    val testNotOverridden: Signal1<String> by signal("blubb")
+    val testNotOverridden by signal1<String>("blubb")
 
     @RegisterSignal
-    open val testOverridden: Signal2<String, Int> by signal("blubb", "habbalubb")
+    open val testOverridden  by signal2<String, Int>("blubb", "habbalubb")
 
     //---------------- Here to check ------------------
 

harness/tests/src/main/kotlin/godot/tests/inheritance/ClassInheritanceChild.kt

@@ -4,15 +4,14 @@ import godot.annotation.RegisterClass
 import godot.annotation.RegisterFunction
 import godot.annotation.RegisterProperty
 import godot.annotation.RegisterSignal
-import godot.core.Signal2
-import godot.core.signal
+import godot.core.signal2
 import godot.global.GD
 
 @RegisterClass
 class ClassInheritanceChild : ClassInheritanceParent() {
 
     @RegisterSignal
-    override val testOverridden: Signal2<String, Int> by signal("blubb", "habbalubbb")
+    override val testOverridden  by signal2<String, Int>("blubb", "habbalubbb")
 
     //---------------- Here to check ------------------
 

harness/tests/src/main/kotlin/godot/tests/inheritance/ClassInheritanceParent.kt

@@ -6,19 +6,18 @@ import godot.annotation.RegisterFunction
 import godot.annotation.RegisterProperty
 import godot.annotation.RegisterSignal
 import godot.core.GodotNotification
-import godot.core.Signal1
-import godot.core.Signal2
-import godot.core.signal
+import godot.core.signal1
+import godot.core.signal2
 import godot.global.GD
 
 @RegisterClass
 open class ClassInheritanceParent : Node() {
 
     @RegisterSignal
-    val testNotOverridden: Signal1<String> by signal("blubb")
+    val testNotOverridden by signal1<String>("blubb")
 
     @RegisterSignal
-    open val testOverridden: Signal2<String, Int> by signal("blubb", "habbalubb")
+    open val testOverridden by signal2<String, Int>("blubb", "habbalubb")
 
     //---------------- Here to check ------------------