Proof class_name PR by Will, add extra picture

getting_started/scripting/gdscript/gdscript_basics.rst

@@ -59,7 +59,7 @@ here's a simple example of how GDScript looks.
 
     extends BaseClass
 
-    # optional script class with optional icon
+    # (optional) class definition with a custom icon
 
     class_name MyClass, "res://path/to/optional/icon.svg"
 
@@ -868,37 +868,62 @@ Multipatterns:
 Classes
 ~~~~~~~
 
-By default, the body of a script file is an unnamed class and it can
-only be referenced externally as a resource or file. Users can also define
-an explicit name for a script using the 'class_name' keyword, optionally
-followed by a path to an image resource. Named scripts appear in Godot
-Engine's editor with their base class icon or the custom defined icon.
-
-Class syntax is meant to be very compact and can only contain member variables
-or functions. Static functions are allowed, but not static members (this is
-in the spirit of thread safety, since scripts can be initialized in
-separate threads without the user knowing). In the same way, member
-variables (including arrays and dictionaries) are initialized every time
-an instance is created.
-
-Below is an example of a class file.
+By default, all script files are unnamed classes. In this case, you can only
+reference them using the file's path, using either a relative or an absolute
+path. For example, if you name a script file ``character.gd``
 
 ::
 
-    # Saved as a file named 'myclass.gd'.
-    
-    class_name MyClass
+   # Inherit from Character.gd
 
-    var a = 5
+   extends res://path/to/character.gd
 
-    func print_value_of_a():
-        print(a)
-    
-    func print_script_three_times():
+   # Load character.gd and create a new node instance from it
+
+   var Character = load("res://path/to/character.gd")
+   var character_node = Character.instance()
+
+Instead, you can give your class a name to register it as a new type in Godot's
+editor. For that, you use the 'class_name' keyword followed. You can add an
+optional comma followed by a path to an image, to use it as an icon. Your class
+will then appear with its new icon in the editor:
+
+::
+
+   # Item.gd
+
+   extends Node
+
+   class_name Item, "res://interface/icons/item.png"
+
+.. image:: img/class_name_editor_register_example.png
+
+Here's a class file example:
+
+::
+
+    # Saved as a file named 'character.gd'.
+
+    class_name Character
+
+    var health = 5
+
+    func print_health():
+        print(health)
+
+    func print_this_script_three_times():
         print(get_script())
         print(ResourceLoader.load("res://myclass.gd"))
         print(MyClass)
 
+
+.. note:: Godot's class syntax is compact: it can only contain member variables or
+          functions. You can use static functions, but not static member variables. In the
+          same way, the engine initializes variables every time you create an instance,
+          and this includes arrays and dictionaries. This is in the spirit of thread
+          safety, since scripts can be initialized in separate threads without the user
+          knowing.
+
 Inheritance
 ^^^^^^^^^^^
 

getting_started/step_by_step/scripting_continued.rst

@@ -6,7 +6,7 @@ Scripting (continued)
 Processing
 ----------
 
-Several actions in Godot are triggered by callbacks or virtual functions, 
+Several actions in Godot are triggered by callbacks or virtual functions,
 so there is no need to write code that runs all the time.
 
 However, it is still common to need a script to be processed on every
@@ -28,7 +28,7 @@ how many frames per second (FPS) the application is running at:
         pass
 
  .. code-tab:: csharp
-    
+
     public override void _Process(float delta)
     {
         // Do something...
@@ -37,7 +37,7 @@ how many frames per second (FPS) the application is running at:
 The delta parameter contains the time elapsed in seconds, as a
 floating point, since the previous call to ``_process()``.
 
-This parameter can be used to make sure things always take the same 
+This parameter can be used to make sure things always take the same
 amount of time, regardless of the game's FPS.
 
 For example, movement is often multiplied with a time delta to make movement
@@ -49,7 +49,7 @@ It always runs before a physics step and it is called at fixed time intervals:
 60 times per second by default. You can change the interval from the Project Settings, under
 Physics -> Common -> Physics Fps.
 
-The function ``_process()``, however, is not synced with physics. Its frame rate is not constant and is dependent 
+The function ``_process()``, however, is not synced with physics. Its frame rate is not constant and is dependent
 on hardware and game optimization. Its execution is done after the physics step on single-threaded games.
 
 A simple way to test this is to create a scene with a single Label node,
@@ -67,7 +67,7 @@ with the following script:
         text = str(accum) # 'text' is a built-in label property.
 
  .. code-tab:: csharp
-    
+
     public class CustomLabel : Label
     {
         private float _accum;
@@ -99,11 +99,11 @@ which are enemies:
         add_to_group("enemies")
 
  .. code-tab:: csharp
-        
+
     public override void _Ready()
     {
         base._Ready();
-        
+
         AddToGroup("enemies");
     }
 
@@ -118,7 +118,7 @@ all enemies can be notified about its alarm sounding by using
         get_tree().call_group("enemies", "player_was_discovered")
 
  .. code-tab:: csharp
-    
+
     public void _OnDiscovered() // This is a purely illustrative function.
     {
         GetTree().CallGroup("enemies", "player_was_discovered");
@@ -137,7 +137,7 @@ calling
     var enemies = get_tree().get_nodes_in_group("enemies")
 
  .. code-tab:: csharp
-    
+
     var enemies = GetTree().GetNodesInGroup("enemies");
 
 The :ref:`SceneTree <class_SceneTree>` class provides many useful methods,
@@ -153,7 +153,7 @@ Notifications
 Godot has a system of notifications. These are usually not needed for
 scripting, as it's too low-level and virtual functions are provided for
 most of them. It's just good to know they exist. For example,
-you may add an 
+you may add an
 :ref:`Object._notification() <class_Object__notification>`
 function in your script:
 
@@ -226,7 +226,7 @@ follows, can be applied to nodes:
         pass
 
  .. code-tab:: csharp
- 
+
     public override void _EnterTree()
     {
         // When the node enters the _Scene Tree_, it becomes active
@@ -270,7 +270,7 @@ the notification system.
 Creating nodes
 --------------
 
-To create a node from code, call the ``.new()`` method, like for any 
+To create a node from code, call the ``.new()`` method, like for any
 other class-based datatype. For example:
 
 
@@ -289,7 +289,7 @@ other class-based datatype. For example:
     public override void _Ready()
     {
         base._Ready();
-    
+
         _sprite = new Sprite(); // Create a new sprite!
         AddChild(_sprite); // Add it as a child of this node.
     }
@@ -348,7 +348,7 @@ first one is to load the scene from your hard drive:
     var scene = load("res://myscene.tscn") # Will load when the script is instanced.
 
  .. code-tab:: csharp
-    
+
     var scene = (PackedScene)ResourceLoader.Load("res://myscene.tscn"); // Will load when the script is instanced.
 
 
@@ -373,7 +373,7 @@ the active scene:
     add_child(node)
 
  .. code-tab:: csharp
-    
+
     var node = scene.Instance();
     AddChild(node);
 
@@ -382,20 +382,17 @@ kept loaded and ready to use so that you can create as many
 instances as desired. This is especially useful to quickly instance
 several enemies, bullets, and other entities in the active scene.
 
-Script Classes
---------------
+Register Scripts as Classes
+---------------------------
 
-Godot has a "Script Class" feature to register individual scripts with the 
-Editor. By default, unnamed scripts are only accessible by loading the file 
-directly. Users name the script and give it an optional icon. These name-script 
-pairings are then supplied to scripting languages in Godot. The named scripts 
-that derive Node or Resource will show up in their respective creation dialogs 
-in the Editor.
+Godot has a "Script Class" feature to register individual scripts with the
+Editor. By default, you can only access unnamed scripts by loading the file
+directly.
 
-At this time...
-
-- Only GDScript and NativeScript (C++ and other GDNative-powered languages) can register scripts.
-- Only GDScript creates global variables for each named script.
+You can name a script and register it as a type in the editor with the
+``class_name`` keyword followed by the class's name. You may add a comma and an
+optional path to an image to use as an icon. You will then find your new type in
+the Node or Resource creation dialog.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -406,10 +403,15 @@ At this time...
     class_name ScriptName, "res://path/to/optional/icon.svg"
 
     func _ready():
-        var this = ScriptName           # script
-        var cppNode = MyCppNode.new()   # instance of a script
+        var this = ScriptName           # reference to the script
+        var cppNode = MyCppNode.new()   # new instance of a class named MyCppNode
 
         cppNode.queue_free()
 
 .. image:: img/script_class_nativescript_example.png
 
+
+.. warning:: In Godot 3.1:
+
+            - Only GDScript and NativeScript, i.e., C++ and other GDNative-powered languages, can register scripts.
+            - Only GDScript creates global variables for each named script.