Add a small tutorial on using Resource scripts. #1768

willnationsdev · 2018-09-29T05:38:24Z

I can't vouch (at all) for the C# snippets in here, so someone more familiar with Godot's C# syntax will have to proofread those. I'm also not sure if my links are executed properly and whether I can safely nest code snippets within a note or warning (as I've done here).

This should finally help people get a better idea of how useful Resource scripts can be, how to make them, and how to use them.

mhilbrunner · 2018-10-01T10:48:11Z

Thanks for this! I'll proofread - FYI, building the docs yourself locally is a great way to verify how it looks in the output, and isn't too hard: Look at the Building with Sphinx section of the README in this repository.

willnationsdev · 2018-10-01T20:56:57Z

@mhilbrunner I got it rendering locally (yay!), so I've fixed up a bunch of stuff with the syntax, however I can't seem to figure out how I'm supposed to make the "script classes" link work. It's supposed to link to the "Scripting Continued" page at the "Register scripts as classes" header, but all the variations I've tried (like :ref:`script classes <scripting_continued#register-scripts-as-classes>`) don't seem to work.

LikeLakers2 · 2018-10-01T20:59:54Z

getting_started/step_by_step/resources.rst

+
+- Resources can even serialize sub-Resources recursively, meaning users can design even more sophisticated data structures.
+
+- Users can save Resources as version-control-friendly text files (\*.tres). Upon exporting a game, Godot serializes resource files as binary files (\*.res) for increased compression.


Aren't *.res files also faster to load?

Yes, because the same amount of data is packed into a smaller space, so it doesn't take as long to parse the data as input.

I suppose I could do "for increased speed and compression" instead.

getting_started/step_by_step/resources.rst

LikeLakers2 · 2018-10-01T21:03:54Z

getting_started/step_by_step/resources.rst

+    With GDScript, it only supports Resource classes at the top level. Defining
+    a Resource subclass, i.e. an inner class, within a GDScript file will have no 
+    effect. If one attempts to save an instance of a Resource subclass, none of 
+    the scripted properties will serialize to the saved file.


This sounds like a bug to me. I've saved ShaderMaterials with Shader resources inside them before, so I don't see why this should be any different.

You can have sub resources within scripts, but if you try to define an entirely new type of Resource as a subclass within another script, then Godot isn't going to identify the path for the script on that resource as "path to the file that has the Resource subclass AND somehow mark that you need to assign the constant value of the subclass Script resource as the script value for the created *.tres. You know, something like "res://file.gd#MyResource" or what-have-you.

Like, if I make a Resource object and set it's script to be not another script file, but a Resource class that's a subclass of a script file (where the script file could derive ANYTHING), it won't start serializing those script properties properly or anything.

Sure, sounds good.

Ah... I think that's my bad for the misunderstanding, then.

That being said, it might be worth trying to reword this paragraph, as I get the feeling it can still come off as ambiguous, not making a clear enough distinction between inner classes and subresources.

Sure, sounds good.

By the way, I deleted my first response to your reply because I realized I completely misunderstood what you were going for, and decided it'd be better to remake my comment.

williamd1k0 · 2018-10-01T21:04:09Z

getting_started/step_by_step/resources.rst

+.. note::
+
+   Resource scripts are similar to Unity's ScriptableObjects. However, unlike in
+   Unity, there is no need to implement IMGUI logic to enable users to create


In fact, there is no need to implement immediate gui or custom editor to use a "common" ScriptableObject.

The current workflow (I tested it in Unity 2018.3):

Create your ScriptableObject class:

public class CustomData : ScriptableObject { public string data; }

Add it to Assets->Create menu:

// This is equivalent to `class_name` in Godot 3.1+ [CreateAssetMenu(menuName="MyCustomStuff/CustomData")] public class CustomData : ScriptableObject { public string data; }

Create a component that will use your ScriptableObject:

public class MyComponent : MonoBehaviour { public CustomData data; }

Create your asset using the Assets->Create menu;

Drag and drop it to the data field in the inspector.

Oh, interesting. That's news to me. Great that they added that feature! Appreciate the heads-up. I'll go ahead and take out that tidbit then.

Unity docs and changelogs are pretty confusing so I don't know in which version this started to work this way 😅

willnationsdev · 2018-10-01T21:28:02Z

@williamd1k0 @LikeLakers2 Updated the document to reflect all of the changes.

willnationsdev · 2018-10-01T21:48:59Z

Okay, finally figured out how to make the script classes link work (just doing an absolute link via URL rather than relative one with :ref:).

exts · 2018-10-02T14:49:00Z

getting_started/step_by_step/resources.rst

+            public int health;
+
+            [Export]
+            public Resource subResource;


http://docs.godotengine.org/en/latest/getting_started/scripting/c_sharp/c_sharp_style_guide.html#naming-conventions

public methods/properties need to be PascalCase. Update this for every property.

mhilbrunner · 2018-10-02T14:48:53Z

getting_started/step_by_step/resources.rst

+scripts grant all the same benefits as the base Resource object. They
+inherit both reference-counting memory management and automatic serialization
+between binary or text data (\*.res, \*.tres) and in-memory object
+properties.


Resource scripts grant all the same benefits as the base Resource object.
They inherit both reference-counting memory management and automatic serialization
between binary or text data (*.res, *.tres) and in-memory object properties.

This is IMO very complex. We need to avoid overwhelming users with cognitive overload :)

How about:

Resource scripts inherit all the same benefits as the base Resource object:
Automatic memory management using reference counting, automatic serialization
between binary or text data (*.res, *.tres) and in-memory object properties.

How about...

As Resources, Resource scripts inherit the ability to freely translate between object properties and serialized text or binary data (*.tres, *.res). They also inherit the reference-counting memory management from the Reference type.

Sound better?

exts · 2018-10-02T14:50:20Z

getting_started/step_by_step/resources.rst

+
+        public class BotStatsTable : Resource
+        {
+            private Godot.Dictionary<String, BotStats> stats = new Godot.Dictionary<String, BotStats>();


Use underscore prefix for private members & update other occurrences across the board http://docs.godotengine.org/en/latest/getting_started/scripting/c_sharp/c_sharp_style_guide.html#naming-conventions

exts · 2018-10-02T14:51:48Z

getting_started/step_by_step/resources.rst

+        public class Bot : KinematicBody
+        {
+            [Export]
+            public BotStats stats;


change to PascalCase http://docs.godotengine.org/en/latest/getting_started/scripting/c_sharp/c_sharp_style_guide.html#naming-conventions

exts · 2018-10-02T14:52:11Z

getting_started/step_by_step/resources.rst

+            public Resource subResource;
+
+            [Export]
+            public String[] strArray;


Change to PascalCase http://docs.godotengine.org/en/latest/getting_started/scripting/c_sharp/c_sharp_style_guide.html#naming-conventions

exts · 2018-10-02T14:52:19Z

getting_started/step_by_step/resources.rst

+        public class BotStats : Resource
+        {
+            [Export]
+            public int health;


Change to PascalCase http://docs.godotengine.org/en/latest/getting_started/scripting/c_sharp/c_sharp_style_guide.html#naming-conventions

willnationsdev · 2018-10-02T16:49:36Z

@mhilbrunner @exts updated to reflect the syntax changes and the rewording of the introductory paragraph. I have also added an additional warning and code segment for GDScript (not even sure if a C# example would apply for the warning since it has to do with Dictionary vs. Resource memory management and I don't know if C# GC's Dictionaries). I also fixed a few rendering errors that were preventing the examples from showing up.

willnationsdev · 2018-10-02T16:52:23Z

Oh, also, I realized that I've been mixing and matching my C# code examples' syntax for allocating objects, but I don't see anything in the docs to indicate what it looks like in the style guide or API differences. Which of these would be used?

MyResource res = new MyResource(10);
MyResource res = MyResource.new(10);

And am I supposed to implement an _Init() override, or do I define a constructor?

KellyThomas · 2018-10-02T16:58:23Z

getting_started/step_by_step/resources.rst

+                [Export]
+                public String[] Strings { get; set; }
+
+                public override void _Init(int health = 0, Resource subResource = null, String[] strings = [])


C Sharp's _Init() implementation is parameterless.
This might be best as a constructor:

public BotStats(...)

Default parameters must be compile time constants.
I suggest using String[] pStrArray = null instead

KellyThomas · 2018-10-02T16:58:45Z

getting_started/step_by_step/resources.rst

+                {
+                    Health = health;
+                    SubResource = subResource;
+                    Strings = strings;


Here you can use strArray = pStrArray ?? new String[0]; to tidy up the default parameter.

KellyThomas · 2018-10-02T16:59:28Z

getting_started/step_by_step/resources.rst

+            public class Bot : KinematicBody
+            {
+                [Export]
+                public BotStats Stats;


The BotStats' type is not currently displayed in the inspector.
This means that exporting this variable only presents the opportunity for users to select the wrong type.

If there isn't a way to export the type (scripted types may not be supported this way?), perhaps something where we export Resource, but then do a runtime check that the type extends BotStats.

BotStats is not displayed in the Create New Resource dialog either.
Its unclear to me how to create one using the editor GUI.

Yeah, this seems like a deeper issue than I realized. godotengine/godot#22641

As for right now, you basically HAVE to export it as an engine type (Resource or some derivative that is still in the engine) and then check if the runtime instance is a script at runtime.

KellyThomas · 2018-10-02T17:00:07Z

getting_started/step_by_step/resources.rst

+
+                public override void _Init()
+                {
+                    if (!Stats)


To perform a null check we should use:

if (stats == null)

KellyThomas · 2018-10-02T17:01:17Z

getting_started/step_by_step/resources.rst

+                {
+                    if (!Stats)
+                    {
+                        Stats = (ResourceLoader::load("BotStats.cs") as BotStats).new(10);


If we are using the constructor as suggested above we can use:

stats = new BotStats(10);

KellyThomas · 2018-10-02T17:04:23Z

getting_started/step_by_step/resources.rst

+                [Export]
+                public BotStats Stats;
+
+                public override void _Init()


While testing this code I found that _Init() isn't being called (godotengine/godot#22633).

getting_started/step_by_step/resources.rst

willnationsdev · 2018-10-02T19:57:11Z

Updated to reflect all changes and relevant Issues.

KellyThomas · 2018-10-02T22:46:55Z

getting_started/step_by_step/resources.rst

+        public class MyNode : Node
+        {
+
+            public class MyResource : Resource {


Looks pretty good now, just a couple of smaller points.
This brace would be best on the next line.

KellyThomas · 2018-10-02T23:38:53Z

getting_started/step_by_step/resources.rst

+                public override void _Ready()
+                {
+                    if (Stats != null && Stats is BotStats) {
+                        Godot.print((Stats as BotStats).Health);


Also this should be GD.Print().

NathanLovato · 2018-10-04T01:56:41Z

Thanks much for your work!

willnationsdev · 2018-10-04T02:24:08Z

Oh, I hadn't made those last two changes yet (moving the brace and changing Godot.print() to GD.Print()). @NathanLovato

NathanLovato · 2018-10-04T03:46:35Z

Sorry, just added the two small changes!

willnationsdev force-pushed the res-script branch 2 times, most recently from 1d7cfd5 to babdcc7 Compare October 1, 2018 20:41

LikeLakers2 reviewed Oct 1, 2018

View reviewed changes

getting_started/step_by_step/resources.rst Show resolved Hide resolved

LikeLakers2 reviewed Oct 1, 2018

View reviewed changes

williamd1k0 reviewed Oct 1, 2018

View reviewed changes

willnationsdev force-pushed the res-script branch from babdcc7 to 59208b8 Compare October 1, 2018 21:27

willnationsdev force-pushed the res-script branch 2 times, most recently from 64ff075 to c4ae77b Compare October 1, 2018 21:48

exts reviewed Oct 2, 2018

View reviewed changes

mhilbrunner reviewed Oct 2, 2018

View reviewed changes

exts reviewed Oct 2, 2018

View reviewed changes

willnationsdev force-pushed the res-script branch from c4ae77b to 44f46a1 Compare October 2, 2018 16:47

KellyThomas reviewed Oct 2, 2018

View reviewed changes

getting_started/step_by_step/resources.rst Show resolved Hide resolved

Add a small tutorial on using Resource scripts.

0b488f4

willnationsdev force-pushed the res-script branch from 44f46a1 to 0b488f4 Compare October 2, 2018 19:56

KellyThomas reviewed Oct 2, 2018

View reviewed changes

NathanLovato merged commit 43aa1c0 into godotengine:master Oct 4, 2018

willnationsdev mentioned this pull request Oct 4, 2018

Tidy up resource script tutorial changes #1790

Closed

williamd1k0 mentioned this pull request Oct 4, 2018

Add Script Serialization info in Unity to Godot page #1791

Merged


		- Resources can even serialize sub-Resources recursively, meaning users can design even more sophisticated data structures.

		- Users can save Resources as version-control-friendly text files (\.tres). Upon exporting a game, Godot serializes resource files as binary files (\.res) for increased compression.

Add a small tutorial on using Resource scripts. #1768

Add a small tutorial on using Resource scripts. #1768

Conversation

willnationsdev commented Sep 29, 2018

mhilbrunner commented Oct 1, 2018

willnationsdev commented Oct 1, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LikeLakers2 Oct 1, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LikeLakers2 Oct 1, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

willnationsdev commented Oct 1, 2018

willnationsdev commented Oct 1, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

willnationsdev Oct 2, 2018 • edited Loading

Choose a reason for hiding this comment

exts Oct 2, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

willnationsdev commented Oct 2, 2018

willnationsdev commented Oct 2, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

willnationsdev commented Oct 2, 2018

KellyThomas Oct 2, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NathanLovato commented Oct 4, 2018

willnationsdev commented Oct 4, 2018

NathanLovato commented Oct 4, 2018

LikeLakers2 Oct 1, 2018 •

edited

Loading

LikeLakers2 Oct 1, 2018 •

edited

Loading

willnationsdev Oct 2, 2018 •

edited

Loading

exts Oct 2, 2018 •

edited

Loading

willnationsdev commented Oct 2, 2018 •

edited

Loading

KellyThomas Oct 2, 2018 •

edited

Loading