From aa223c335cf389a9b7e3481c27148b7a9eb3dd59 Mon Sep 17 00:00:00 2001 From: Mark Wilson <23439518+wlsnmrk@users.noreply.github.com> Date: Sun, 8 Oct 2023 17:51:46 -0400 Subject: [PATCH] Improved style for cross-language examples. * Replaced "foo"/"bar" example values with "my value". * Changed C# public field to property and GDScript to match. * Used PascalCase for C# property. * Used camelCase for C# local variable. * Used "var" for C# local variable declarations. * Used PascalCase for GDScript class/script variable. * Improved clarity of comments documenting expected output. * Eliminated horizontal scroll in C# code example. * Fixed a comma splice in the page text. * Removed an out-of-date warning block. --- .../scripting/cross_language_scripting.rst | 74 +++++++++++-------- 1 file changed, 43 insertions(+), 31 deletions(-) diff --git a/tutorials/scripting/cross_language_scripting.rst b/tutorials/scripting/cross_language_scripting.rst index 8b193e1b8..fd9f5bb55 100644 --- a/tutorials/scripting/cross_language_scripting.rst +++ b/tutorials/scripting/cross_language_scripting.rst @@ -16,7 +16,11 @@ The following two scripts will be used as references throughout this page. extends Node - var my_field: String = "foo" + var my_property: String = "my gdscript value": + get: + return my_property + set(value): + my_property = value signal my_signal @@ -40,7 +44,7 @@ The following two scripts will be used as references throughout this page. public partial class MyCSharpNode : Node { - public string myField = "bar"; + public string MyProperty { get; set; } = "my c# value"; [Signal] public delegate void MySignalEventHandler(); @@ -86,8 +90,8 @@ with :ref:`new() `. .. code-block:: gdscript - var my_csharp_script = load("res://Path/To/MyCSharpNode.cs") - var my_csharp_node = my_csharp_script.new() + var MyCSharpScript = load("res://Path/To/MyCSharpNode.cs") + var my_csharp_node = MyCSharpScript.new() .. warning:: @@ -112,8 +116,8 @@ be instantiated with :ref:`GDScript.New() `. .. code-block:: csharp - GDScript MyGDScript = GD.Load("res://path/to/my_gd_script.gd"); - GodotObject myGDScriptNode = (GodotObject)MyGDScript.New(); // This is a GodotObject. + var myGDScript = GD.Load("res://path/to/my_gd_script.gd"); + var myGDScriptNode = (GodotObject)myGDScript.New(); // This is a GodotObject. Here we are using an :ref:`class_Object`, but you can use type conversion like explained in :ref:`doc_c_sharp_features_type_conversion_and_casting`. @@ -129,22 +133,26 @@ anything to worry about. .. code-block:: gdscript - print(my_csharp_node.myField) # bar - my_csharp_node.myField = "BAR" - print(my_csharp_node.myField) # BAR + # Output: "my c# value". + print(my_csharp_node.MyProperty) + my_csharp_node.MyProperty = "MY C# VALUE" + # Output: "MY C# VALUE". + print(my_csharp_node.MyProperty) Accessing GDScript fields from C# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As C# is statically typed, accessing GDScript from C# is a bit more -convoluted, you will have to use :ref:`GodotObject.Get() ` +convoluted. You will have to use :ref:`GodotObject.Get() ` and :ref:`GodotObject.Set() `. The first argument is the name of the field you want to access. .. code-block:: csharp - GD.Print(myGDScriptNode.Get("my_field")); // foo - myGDScriptNode.Set("my_field", "FOO"); - GD.Print(myGDScriptNode.Get("my_field")); // FOO + // Output: "my gdscript value". + GD.Print(myGDScriptNode.Get("my_property")); + myGDScriptNode.Set("my_property", "MY GDSCRIPT VALUE"); + // Output: "MY GDSCRIPT VALUE". + GD.Print(myGDScriptNode.Get("my_property")); Keep in mind that when setting a field value you should only use types the GDScript side knows about. @@ -163,13 +171,18 @@ If that's impossible, you'll see the following error: ``Invalid call. Nonexisten .. code-block:: gdscript - my_csharp_node.PrintNodeName(self) # myGDScriptNode - # my_csharp_node.PrintNodeName() # This line will fail. + # Output: "my_gd_script_node" (or name of node where this code is placed). + my_csharp_node.PrintNodeName(self) + # This line will fail. + # my_csharp_node.PrintNodeName() - my_csharp_node.PrintNTimes("Hello there!", 2) # Hello there! Hello there! + # Outputs "Hello there!" twice, once per line. + my_csharp_node.PrintNTimes("Hello there!", 2) - my_csharp_node.PrintArray(["a", "b", "c"]) # a, b, c - my_csharp_node.PrintArray([1, 2, 3]) # 1, 2, 3 + # Output: "a", "b", "c" (one per line). + my_csharp_node.PrintArray(["a", "b", "c"]) + # Output: "1", "2", "3" (one per line). + my_csharp_node.PrintArray([1, 2, 3]) Calling GDScript methods from C# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -181,22 +194,21 @@ to said method. .. code-block:: csharp - myGDScriptNode.Call("print_node_name", this); // my_csharp_node - // myGDScriptNode.Call("print_node_name"); // This line will fail silently and won't error out. + // Output: "MyCSharpNode" (or name of node where this code is placed). + myGDScriptNode.Call("print_node_name", this); + // This line will fail silently and won't error out. + // myGDScriptNode.Call("print_node_name"); - myGDScriptNode.Call("print_n_times", "Hello there!", 2); // Hello there! Hello there! + // Outputs "Hello there!" twice, once per line. + myGDScriptNode.Call("print_n_times", "Hello there!", 2); string[] arr = new string[] { "a", "b", "c" }; - myGDScriptNode.Call("print_array", arr); // a, b, c - myGDScriptNode.Call("print_array", new int[] { 1, 2, 3 }); // 1, 2, 3 - // Note how the type of each array entry does not matter as long as it can be handled by the marshaller. - -.. warning:: - - As you can see, if the first argument of the called method is an array, - you'll need to cast it as ``object``. - Otherwise, each element of your array will be treated as a single argument - and the function signature won't match. + // Output: "a", "b", "c" (one per line). + myGDScriptNode.Call("print_array", arr); + // Output: "1", "2", "3" (one per line). + myGDScriptNode.Call("print_array", new int[] { 1, 2, 3 }); + // Note how the type of each array entry does not matter + // as long as it can be handled by the marshaller. .. _connecting_to_signals_cross_language: