From aa9f58ec1687274e80ee2d04b5c8cce0acf48a9f Mon Sep 17 00:00:00 2001 From: Ivan-267 <61947090+Ivan-267@users.noreply.github.com> Date: Wed, 8 May 2024 16:39:42 +0200 Subject: [PATCH 1/7] Create WORKING_WITH_C_SHARP.md --- docs/WORKING_WITH_C_SHARP.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 docs/WORKING_WITH_C_SHARP.md diff --git a/docs/WORKING_WITH_C_SHARP.md b/docs/WORKING_WITH_C_SHARP.md new file mode 100644 index 00000000..2e3c66b7 --- /dev/null +++ b/docs/WORKING_WITH_C_SHARP.md @@ -0,0 +1,17 @@ +# Working with C# + +While the Godot RL Agents Godot plugin currently natively supports only working with gdscript and this option is recommended, +it is possible to use C# for your projects as well. The process is slightly more complicated, so some understanding of +how the gdscript variant of the plugin works is recommended. + +We recommended completing the [custom env](https://github.com/edbeeching/godot_rl_agents/blob/main/docs/CUSTOM_ENV.md) tutorial first using +gdscript to get an idea of the usual process with gdscript first. + +We have prepared a simple example that comes in 3 variants: +- GDScript [TODO: LINK] (the entire game is written in gdscript) +- CSharp [TODO: LINK] (most of the game is written in C#, except for the extended AIController which is written in GDScript) +- CSharpAll [TODO: LINK] (the game is written in C#, and an AIController wrapper is written in C# as well) + +A brief comparison of the two C# approaches: +### CSharp +### CSharpAll From 466d7cd8cf528196428d369cacb387a72a3252ba Mon Sep 17 00:00:00 2001 From: Ivan-267 <61947090+Ivan-267@users.noreply.github.com> Date: Wed, 8 May 2024 16:40:13 +0200 Subject: [PATCH 2/7] Rename WORKING_WITH_C_SHARP.md to WORKING_WITH_CSHARP.md --- docs/{WORKING_WITH_C_SHARP.md => WORKING_WITH_CSHARP.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{WORKING_WITH_C_SHARP.md => WORKING_WITH_CSHARP.md} (100%) diff --git a/docs/WORKING_WITH_C_SHARP.md b/docs/WORKING_WITH_CSHARP.md similarity index 100% rename from docs/WORKING_WITH_C_SHARP.md rename to docs/WORKING_WITH_CSHARP.md From dd839900f86c6ca9957488b8093832758dda5d2a Mon Sep 17 00:00:00 2001 From: LorinczAdrien Date: Sat, 11 May 2024 14:30:38 +0300 Subject: [PATCH 3/7] Updated WORKING_WITH_CSHARP.md with CSharpAll variant details --- docs/WORKING_WITH_CSHARP.md | 46 +++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/WORKING_WITH_CSHARP.md b/docs/WORKING_WITH_CSHARP.md index 2e3c66b7..df99b901 100644 --- a/docs/WORKING_WITH_CSHARP.md +++ b/docs/WORKING_WITH_CSHARP.md @@ -13,5 +13,51 @@ We have prepared a simple example that comes in 3 variants: - CSharpAll [TODO: LINK] (the game is written in C#, and an AIController wrapper is written in C# as well) A brief comparison of the two C# approaches: +1. CSharp: +2. CSharpAll: The entire game is written in C#, and interfacing with the plugin is done through an AIController also +written in C#. + +[//]: # "TODO: What elso should we add here? Should we combine this brief comparison with the listing above?" + ### CSharp + ### CSharpAll + +As mentioned the _CSharpAll_ variant of this example has the entire game written in C#, aiming to provide a more +consistent experience for C# developers. The main advantage of this approach is that interfacing with the AIController +no longer assumes [cross-language scripting](https://docs.godotengine.org/en/stable/tutorials/scripting/cross_language_scripting.html) between C# and GDScript. + +This approach is slightly more complicated to set up than the _CSharp_ variant, as it requires a custom C# wrapper for +the `ai_controller_3d.gd` node. We provide this wrapper called `AIControllerSharp3D.cs` [here](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/CSharpAll/scenes/player/AIControllerSharp3D.cs), +but it should be noted that this wrapper may not be kept up to date with the GDScript version, as such it may need small +changes in the future to work. + +[//]: # "TODO: Change `AIControllerSharp3D.cs` branch infix to main when merged" + +#### Using the C# AIController + +As we did in the other examples, we need to inherit from the AIController node, only now we will inherit from the +provided C# wrapper. Upon inheriting, you will find the C# equivalent of the GDScript AIController functions that you +need to add logic to, see this section of [custom env](https://github.com/edbeeching/godot_rl_agents/blob/main/docs/CUSTOM_ENV.md#adding-the-ai-controller) tutorial for more details. + +As mentioned before, by writing the AIController in C# we eliminate [cross-language scripting](https://docs.godotengine.org/en/stable/tutorials/scripting/cross_language_scripting.html) between the 'player' +C# script and the AIController script, but this does mean that interfacing with other GDScript nodes, such as the +sensors provided by the plugin, means a minimal cross-language scripting is still required. This example also showcases +how to inferface with these components (see [PlayerAIController.cs](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/CSharpAll/scenes/player/PlayerAIController.cs)). + +[//]: # "TODO: Change `PlayerAIController` branch infix to main when merged" + +#### Modifying the AIController 3D wrapper to 2D version + +In case you want to use the 2D version of the AIController, you will need to modify the provided +`AIControllerSharp3D.cs` in a few minor ways: +- Change the class name to `AIControllerSharp2D` and the base class to `Node2D` +```diff +- public abstract partial class AIControllerSharp3D : Node3D ++ public abstract partial class AIControllerSharp2D : Node2D +``` +- Change the `_player` field to be of type `Node3D` instead of `Node2D` +```diff +- public Node2D _player; ++ public Node3D _player; +``` From 8b31dcbce69c2e952ad92992da8cf544150a3d96 Mon Sep 17 00:00:00 2001 From: Ivan-267 <61947090+Ivan-267@users.noreply.github.com> Date: Sat, 11 May 2024 21:34:10 +0200 Subject: [PATCH 4/7] Update WORKING_WITH_CSHARP.md --- docs/WORKING_WITH_CSHARP.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/WORKING_WITH_CSHARP.md b/docs/WORKING_WITH_CSHARP.md index df99b901..ea404ff3 100644 --- a/docs/WORKING_WITH_CSHARP.md +++ b/docs/WORKING_WITH_CSHARP.md @@ -8,18 +8,17 @@ We recommended completing the [custom env](https://github.com/edbeeching/godot_r gdscript to get an idea of the usual process with gdscript first. We have prepared a simple example that comes in 3 variants: -- GDScript [TODO: LINK] (the entire game is written in gdscript) -- CSharp [TODO: LINK] (most of the game is written in C#, except for the extended AIController which is written in GDScript) -- CSharpAll [TODO: LINK] (the game is written in C#, and an AIController wrapper is written in C# as well) +- GDScript [TODO: LINK] (The entire game is written in gdscript) +- CSharp [TODO: LINK] (Most of the game is written in C#, except for the extended AIController which is written in GDScript) +- CSharpAll [TODO: LINK] (The entire game is written in C#, and interfacing with the plugin is done through an AIController also written in C#) -A brief comparison of the two C# approaches: -1. CSharp: -2. CSharpAll: The entire game is written in C#, and interfacing with the plugin is done through an AIController also -written in C#. +### CSharp -[//]: # "TODO: What elso should we add here? Should we combine this brief comparison with the listing above?" +In this approach, we extend the AIController using gdscript as we cannot directly extend from it using C#, but we still write the rest of the game in C# (e.g. Player and other classes). -### CSharp +You can see the [extended AIController here](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/CSharp/scenes/player/player_ai_controller.gd). The code is very is very similar to the gdscript env version [extended AI Controller](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/GDScript/scenes/player/player_ai_controller.gd), except that we don't get code completion for the C# classes. It is slightly more complex to access/modify the AIController properties from the C# Player class, and you can see how that is done in the [Player script](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/CSharp/scenes/player/Player.cs). + +The main advantage of this approach is that it doesn't require any modifications to the plugin, or writing an AIController wrapper (see [CSharpAll](#csharpall) for that approach). It's also easy to access data from [sensors](https://github.com/edbeeching/godot_rl_agents/blob/main/docs/NODE_REFERENCE.md#sensors) included in the plugin which are written in gdscript. The disadvantage is that it uses [cross-language scripting](https://docs.godotengine.org/en/stable/tutorials/scripting/cross_language_scripting.html) when interfacing between the AIController and the Player script and/or the rest of the env code written in C#. ### CSharpAll From b94accbaa7f45e0b00db123e15b6f241796ac780 Mon Sep 17 00:00:00 2001 From: Ivan-267 <61947090+Ivan-267@users.noreply.github.com> Date: Sat, 11 May 2024 21:36:25 +0200 Subject: [PATCH 5/7] Update WORKING_WITH_CSHARP.md Typo fix --- docs/WORKING_WITH_CSHARP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/WORKING_WITH_CSHARP.md b/docs/WORKING_WITH_CSHARP.md index ea404ff3..d136c440 100644 --- a/docs/WORKING_WITH_CSHARP.md +++ b/docs/WORKING_WITH_CSHARP.md @@ -16,7 +16,7 @@ We have prepared a simple example that comes in 3 variants: In this approach, we extend the AIController using gdscript as we cannot directly extend from it using C#, but we still write the rest of the game in C# (e.g. Player and other classes). -You can see the [extended AIController here](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/CSharp/scenes/player/player_ai_controller.gd). The code is very is very similar to the gdscript env version [extended AI Controller](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/GDScript/scenes/player/player_ai_controller.gd), except that we don't get code completion for the C# classes. It is slightly more complex to access/modify the AIController properties from the C# Player class, and you can see how that is done in the [Player script](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/CSharp/scenes/player/Player.cs). +You can see the [extended AIController here](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/CSharp/scenes/player/player_ai_controller.gd). The code is very similar to the gdscript env version [extended AI Controller](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/GDScript/scenes/player/player_ai_controller.gd), except that we don't get code completion for the C# classes. It is slightly more complex to access/modify the AIController properties from the C# Player class, and you can see how that is done in the [Player script](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/CSharp/scenes/player/Player.cs). The main advantage of this approach is that it doesn't require any modifications to the plugin, or writing an AIController wrapper (see [CSharpAll](#csharpall) for that approach). It's also easy to access data from [sensors](https://github.com/edbeeching/godot_rl_agents/blob/main/docs/NODE_REFERENCE.md#sensors) included in the plugin which are written in gdscript. The disadvantage is that it uses [cross-language scripting](https://docs.godotengine.org/en/stable/tutorials/scripting/cross_language_scripting.html) when interfacing between the AIController and the Player script and/or the rest of the env code written in C#. From fd7748d4008b14ee2e761de30a5c59161e885df9 Mon Sep 17 00:00:00 2001 From: Ivan-267 <61947090+Ivan-267@users.noreply.github.com> Date: Sun, 12 May 2024 19:19:55 +0200 Subject: [PATCH 6/7] Update WORKING_WITH_CSHARP.md --- docs/WORKING_WITH_CSHARP.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/WORKING_WITH_CSHARP.md b/docs/WORKING_WITH_CSHARP.md index d136c440..7c579644 100644 --- a/docs/WORKING_WITH_CSHARP.md +++ b/docs/WORKING_WITH_CSHARP.md @@ -55,8 +55,8 @@ In case you want to use the 2D version of the AIController, you will need to mod - public abstract partial class AIControllerSharp3D : Node3D + public abstract partial class AIControllerSharp2D : Node2D ``` -- Change the `_player` field to be of type `Node3D` instead of `Node2D` +- Change the `_player` field to be of type `Node2D` instead of `Node3D` ```diff -- public Node2D _player; -+ public Node3D _player; +- public Node3D _player; ++ public Node2D _player; ``` From 22c459a7511dfb8bfa6044cc9ca4b27f19fcecb7 Mon Sep 17 00:00:00 2001 From: Ivan-267 <61947090+Ivan-267@users.noreply.github.com> Date: Sun, 12 May 2024 21:59:10 +0200 Subject: [PATCH 7/7] Update WORKING_WITH_CSHARP.md Updates links to the main branch and other minor tweaks. --- docs/WORKING_WITH_CSHARP.md | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/docs/WORKING_WITH_CSHARP.md b/docs/WORKING_WITH_CSHARP.md index 7c579644..0a411e15 100644 --- a/docs/WORKING_WITH_CSHARP.md +++ b/docs/WORKING_WITH_CSHARP.md @@ -5,18 +5,18 @@ it is possible to use C# for your projects as well. The process is slightly more how the gdscript variant of the plugin works is recommended. We recommended completing the [custom env](https://github.com/edbeeching/godot_rl_agents/blob/main/docs/CUSTOM_ENV.md) tutorial first using -gdscript to get an idea of the usual process with gdscript first. +gdscript to get an idea of the usual process first. We have prepared a simple example that comes in 3 variants: -- GDScript [TODO: LINK] (The entire game is written in gdscript) -- CSharp [TODO: LINK] (Most of the game is written in C#, except for the extended AIController which is written in GDScript) -- CSharpAll [TODO: LINK] (The entire game is written in C#, and interfacing with the plugin is done through an AIController also written in C#) +- [GDScript](https://github.com/edbeeching/godot_rl_agents_examples/tree/main/examples/TestExamples/SimpleReachGoal/GDScript) (The entire game is written in gdscript) +- [CSharp](https://github.com/edbeeching/godot_rl_agents_examples/tree/main/examples/TestExamples/SimpleReachGoal/CSharp) (Most of the game is written in C#, except for the extended AIController which is written in GDScript) +- [CSharpAll](https://github.com/edbeeching/godot_rl_agents_examples/tree/main/examples/TestExamples/SimpleReachGoal/CSharpAll) (The entire game is written in C#, and interfacing with the plugin is done through an AIController also written in C#) ### CSharp In this approach, we extend the AIController using gdscript as we cannot directly extend from it using C#, but we still write the rest of the game in C# (e.g. Player and other classes). -You can see the [extended AIController here](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/CSharp/scenes/player/player_ai_controller.gd). The code is very similar to the gdscript env version [extended AI Controller](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/GDScript/scenes/player/player_ai_controller.gd), except that we don't get code completion for the C# classes. It is slightly more complex to access/modify the AIController properties from the C# Player class, and you can see how that is done in the [Player script](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/CSharp/scenes/player/Player.cs). +You can see the [extended AIController here](https://github.com/edbeeching/godot_rl_agents_examples/blob/main/examples/TestExamples/SimpleReachGoal/CSharp/scenes/player/player_ai_controller.gd). The code is very similar to the gdscript version [extended AI Controller](https://github.com/edbeeching/godot_rl_agents_examples/blob/main/examples/TestExamples/SimpleReachGoal/GDScript/scenes/player/player_ai_controller.gd), except that we don't get code completion in gdscript for the C# classes. It is slightly more complex to access/modify the gdscript AIController properties from the C# Player class, and you can see how that is done in the [Player script](https://github.com/edbeeching/godot_rl_agents_examples/blob/main/examples/TestExamples/SimpleReachGoal/CSharp/scenes/player/Player.cs). The main advantage of this approach is that it doesn't require any modifications to the plugin, or writing an AIController wrapper (see [CSharpAll](#csharpall) for that approach). It's also easy to access data from [sensors](https://github.com/edbeeching/godot_rl_agents/blob/main/docs/NODE_REFERENCE.md#sensors) included in the plugin which are written in gdscript. The disadvantage is that it uses [cross-language scripting](https://docs.godotengine.org/en/stable/tutorials/scripting/cross_language_scripting.html) when interfacing between the AIController and the Player script and/or the rest of the env code written in C#. @@ -27,12 +27,10 @@ consistent experience for C# developers. The main advantage of this approach is no longer assumes [cross-language scripting](https://docs.godotengine.org/en/stable/tutorials/scripting/cross_language_scripting.html) between C# and GDScript. This approach is slightly more complicated to set up than the _CSharp_ variant, as it requires a custom C# wrapper for -the `ai_controller_3d.gd` node. We provide this wrapper called `AIControllerSharp3D.cs` [here](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/CSharpAll/scenes/player/AIControllerSharp3D.cs), +the `ai_controller_3d.gd` node. We provide this wrapper called `AIControllerSharp3D.cs` [here](https://github.com/edbeeching/godot_rl_agents_examples/blob/main/examples/TestExamples/SimpleReachGoal/CSharpAll/scenes/player/AIControllerSharp3D.cs), but it should be noted that this wrapper may not be kept up to date with the GDScript version, as such it may need small changes in the future to work. -[//]: # "TODO: Change `AIControllerSharp3D.cs` branch infix to main when merged" - #### Using the C# AIController As we did in the other examples, we need to inherit from the AIController node, only now we will inherit from the @@ -42,9 +40,7 @@ need to add logic to, see this section of [custom env](https://github.com/edbeec As mentioned before, by writing the AIController in C# we eliminate [cross-language scripting](https://docs.godotengine.org/en/stable/tutorials/scripting/cross_language_scripting.html) between the 'player' C# script and the AIController script, but this does mean that interfacing with other GDScript nodes, such as the sensors provided by the plugin, means a minimal cross-language scripting is still required. This example also showcases -how to inferface with these components (see [PlayerAIController.cs](https://github.com/edbeeching/godot_rl_agents_examples/blob/AddSimpleTestEnv/examples/TestExamples/SimpleReachGoal/CSharpAll/scenes/player/PlayerAIController.cs)). - -[//]: # "TODO: Change `PlayerAIController` branch infix to main when merged" +how to inferface with these components (see [PlayerAIController.cs](https://github.com/edbeeching/godot_rl_agents_examples/blob/main/examples/TestExamples/SimpleReachGoal/CSharpAll/scenes/player/PlayerAIController.cs)). #### Modifying the AIController 3D wrapper to 2D version