From 8750f7b6d85b1abd6576da54e98810aba5ead223 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Manuel=20Qui=C3=B1ones?= <manuel.por.aca@gmail.com>
Date: Wed, 29 Jan 2025 12:23:28 -0300
Subject: [PATCH 1/3] Update technical documentation

Document BlockDefinition resource and block types using GDScript
documentation comments.

Outside code, rename the current technical document to
`docs/TECH_OVERVIEW.md` to indicate that it's technical. And update it:
- Move "How to create a new block" to the top
- Leave UI technical docs in its own section
- Remove other outdated explanation

It would be nice to also document the AST decouple from the UI, but I'm
no expert to do it.
---
 .../code_generation/block_definition.gd       |  40 ++++++-
 addons/block_code/types/types.gd              |  10 +-
 docs/OVERVIEW.md                              | 108 ------------------
 docs/TECH_OVERVIEW.md                         |  26 +++++
 4 files changed, 68 insertions(+), 116 deletions(-)
 delete mode 100644 docs/OVERVIEW.md
 create mode 100644 docs/TECH_OVERVIEW.md

diff --git a/addons/block_code/code_generation/block_definition.gd b/addons/block_code/code_generation/block_definition.gd
index a4447044..d13ce8bf 100644
--- a/addons/block_code/code_generation/block_definition.gd
+++ b/addons/block_code/code_generation/block_definition.gd
@@ -11,25 +11,59 @@ const FORMAT_STRING_PATTERN = "\\[(?<out_parameter>[^\\]]+)\\]|\\{const (?<const
 ## (for any node).
 @export var target_node_class: String
 
+## A description for this block, which will be shown to the user in a tooltip.
 @export_multiline var description: String
+
+## The category under which this block will appear in the Picker.
 @export var category: String
 
+## Which kind of block is this. See [enum Types.BlockType].
 @export var type: Types.BlockType
+
+## Only relevant for Value blocks. The variant type that this block is
+## supposed to return.
 @export var variant_type: Variant.Type
 
+## Template for creating the UI of this block. That is, the labels and the
+## parameters that will become user inputs with slots. The UI can be split
+## between basic and advanced using the [code]|[/code] character as separator.
+## Example:
+## [codeblock]
+## say {salute: STRING} | {fancy: BOOL}
+## [/codeblock]
 @export var display_template: String
+
+## Template for the generated GDScript code. This must be valid GDScript. The
+## parameters in [member display_template] will be replaced by the user input
+## or by the resulting value of snapped blocks.
+## Following the example in [member display_template]:
+## [codeblock]
+## if {fancy}:
+##     print_rich('[color=green][b]' + {salute} + '[/b][/color]')
+## else:
+##     print({salute})
+## [/codeblock]
 @export_multiline var code_template: String
+
+## Optional defaults for the variables defined in [member display_template].
+## The key must be of type String and match a variable name in both [member
+## display_template] and [member code_template]. The value must be of the same
+## type as defined in the [member display_template].
 @export var defaults: Dictionary
 
-## Only for blocks of type Types.ENTRY. If non-empty, this block defines a
-## callback that will be connected to the signal with this name.
+## Only for blocks of type [member Types.BlockType.ENTRY]. If non-empty, this
+## block defines a callback that will be connected to the signal with this
+## name.
 @export var signal_name: String
 
-## Empty except for blocks that have a defined scope
+## Empty except for blocks that have a defined scope.
 @export var scope: String
 
+## If checked, the block will be hidden by default in the Picker.
 @export var is_advanced: bool
 
+## An optional script that can extend this block definition. For instance, to
+## dynamically add the defaults.
 @export var extension_script: GDScript
 
 static var _display_template_regex := RegEx.create_from_string(FORMAT_STRING_PATTERN)
diff --git a/addons/block_code/types/types.gd b/addons/block_code/types/types.gd
index e1768560..73329bad 100644
--- a/addons/block_code/types/types.gd
+++ b/addons/block_code/types/types.gd
@@ -1,11 +1,11 @@
 extends Node
 
 enum BlockType {
-	NONE,
-	ENTRY,
-	STATEMENT,
-	VALUE,
-	CONTROL,
+	NONE,  ## @deprecated
+	ENTRY,  ## A block that's the entry point. Statement or control blocks can be attached below it.
+	STATEMENT,  ## A block that executes a statement. Another statement or control block can be attached below it.
+	VALUE,  ## A block that represents a value. It could be a constant or the result of an operation. All blocks may have slots to attach value blocks in their body.
+	CONTROL,  ## A block that can conditionally execute other statement or control blocks. Another statement or control block can be attached below it.
 }
 
 const VARIANT_TYPE_TO_STRING: Dictionary = {
diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md
deleted file mode 100644
index 67a6b074..00000000
--- a/docs/OVERVIEW.md
+++ /dev/null
@@ -1,108 +0,0 @@
-# Block Programming Plugin
-
-## Data flow/Hierarchy
-
-1. The plugin enters at `block_code_plugin.gd` (`BlockCodePlugin`) where the `MainPanel` is initialized and added as a main screen tab labeled "Block Code".
-	* The `MainPanel` contains a block `Picker`, a `BlockCanvas`, a `TitleBar`, and a `DragManager`.
-		* The `Picker` contains a combined list of categories of blocks from the global blocks generated in `CategoryFactory`, and custom blocks defined in the class the script is attached to.
-		* The `BlockCanvas` is where placed blocks live, and generates the code from the scene tree of blocks.
-		* The `TitleBar` displays some information about the block script.
-		* The `DragManager` determines how blocks are snapped, and what happens when you drag a block from either the `Picker` or the `BlockCanvas`
-
-2. When a `BlockCode` node is selected, the `MainPanel` supplies the `Picker`, `BlockCanvas`, and `TitleBar` with the `BlockScriptData` (BSD) attached to the `BlockCode` node you clicked.
-	* The `Picker` will be loaded with blocks, and any custom blocks supplied by the parent of the `BlockCode` node you clicked.
-	* The `BlockCanvas` will be populated with the block scene tree deserialized from the BSD (`BlockScriptData.block_trees`).
-	* The `TitleBar` will be populated with the name of class the script inherits.
-	* If the BSD is `null`, it will copy and load the default one.
-
-3. When you click and drag a block from the `Picker`, the `DragManager` is signaled to copy the block and enables you to drag it to the `BlockCanvas`.
-
-4. The `DragManager` looks for the closest compatible snap point within a certain range, and if it exists, will show a preview where your `Block` will go if you drop it.
-	* Each `Block` has a `block_type` property, and so does each snap point. They must match to snap.
-	* If a `Block` has the block type `VALUE`, it should have a `variant_type` property (since it represents a value).
-		* If it is a `VALUE` block, it's `variant_type` must be able to cast to the snap point's `variant_type` in order to snap. This is determined by the cast graph in `types.gd`.
-		* Each `ParameterBlock` is a `VALUE` block which has this `variant_type` property.
-
-5. When the block script is modified, it will regenerate the BSD, and save it as an exported property of the `BlockCode` node you are working on. This way it gets saved to the scene.
-	* The block script is modified when a block is moved, or a `ParameterInput`'s raw input has been changed.
-	* Code is generated whenever you modify the block in `BlockCanvas`.
-
-6. When you play the scene, each `BlockCode` node will attach a generated script from it's BSD to it's parent node. The `_ready` and `_process` methods will start normally.
-
-## How to create a new block
-
-Blocks are created from a template such as `StatementBlock`, `ParameterBlock`, `EntryBlock`, or `ControlBlock`. Blocks are defined programmatically and generated live, they are not saved permanently in any sort of class.
-* `StatementBlock`: Generates a line of code to be executed. Has notches to snap other statement blocks to. Supports input parameters.
-* `ParameterBlock`: Represents a value, or expression in some code. Can be used as input for any statement blocks, or other parameter blocks that also take input.
-* `EntryBlock`: Generates a method header, entry point to block script. Also supports input parameters.
-* `ControlBlock`: Dictates the flow of instruction, such as a loop or if/else statement. Can have multiple slots for calling different statements based on a conditional input.
-
-You can define a block:
-1. Globally in `CategoryFactory.get_general_blocks()`
-2. For a specific built-in class in `CategoryFactory.get_built_in_blocks()`
-3. In a custom class by defining a method `static func get_custom_blocks() -> Array[Block]:`. See `SimpleCharacter` for an example.
-
-Here is an example of generating a `STATEMENT` block:
-```
-# Instantiate the template block. In this case we use a StatementBlock since we want to generate a statement from some parameter inputs.
-var b = BLOCKS["statement_block"].instantiate()
-
-# Define the block format string. This is how the block will be rendered, with some text and two typed inputs.
-# Inputs are specified as {parameter_name: TYPE}
-b.block_format = "Set Int {var: STRING} {value: INT}"
-
-# Define the statement that will be generated from the inputs. Use the parameter name to specify which goes where.
-b.statement = "VAR_DICT[{var}] = {value}"
-
-# Set the category too add the block to.
-b.category = "Variables"
-```
-Look in `CategoryFactory` for more examples!
-
-Each block gets added to a category in the Block Code editor by setting
-the block's `category` property. If you have a custom class, you can add
-a new category by defining a method `static func get_custom_categories()
--> Array[BlockCategory]:`. See `Pong` for an example.
-
-Note: For `EntryBlock`s, you can use the syntax `[param: TYPE]` with square brackets instead of curlies to generate a copyable `ParameterBlock` that can be used in the below method.
-For example, to expose the `delta` argument in `func _on_process(delta):`, you would use the following format string:
-```
-b.block_format = "On Process [delta: FLOAT]"
-```
-
-## What's inside?
-
-* `/addons/block_code/`: The main plugin folder.
-	* `block_code_plugin.gd`: The entry point to the editor plugin. Sets up the `MainPanel` scene which appears as a main screen tab at the top.
-	* `/block_code_node/`: Contains the script for our custom `BlockCode` node that allows you to attach block scripts to a node. You can instantiate it in the scene dock.
-	* `/block_script_data/`: Contains the custom resource that persists each block script. Each resource saves the class it inherits from, the generated script, and the tree of `Block`s to load.
-	* `/drag_manager/`: Should be in the `ui` folder, let's fix that. Handles dragging blocks across the canvas and picker.
-	* `/inspector_plugin/`: An inspector plugin that adds a button to the inspector on `BlockCode` nodes to open the script.
-	* `/instruction_tree/`: A utility script that generates code from a tree of `TreeNode`s. This tree is created by `BlockCanvas` and also recursively by the `Block`s themselves.
-	* `/lib/`: Some scripts from GodotTours that label and expose some of the editor Control nodes so they can be interfaced with.
-	* `/simple_nodes/`: Contains scenes for simple nodes that can be used in a simple game. E.g. `SimpleCharacter` comes with a sprite and collision, and exposes custom movement blocks.
-	* `/types/`: Contains all things related to types in the addon. Types of blocks, casting, and variant to string type conversion.
-	* `/ui/`: Contains scenes and scripts for all UI related things. Block templates, `MainPanel`, etc.
-		* `main_panel.tscn`: Scene for the main addon window. Holds the `Picker`, `BlockCanvas`, `DragManager`, and `TitleBar`
-		* `constants.gd`: Contains various styling and functional constants for the addon.
-		* `/blocks/`: Folder that holds all of the scenes for block templates.
-			* `/block/`: The base class for all blocks.
-			* `/statement_block/`: A block that can generate statements from multiple inputs.
-			* `/parameter_block/`: A block that returns a value generated from multiple inputs.
-			* `/control_block/`: A block that dictates the control flow of the program based on conditions, like if/else.
-			* `/entry_block/`: A block that represents an entry point to the block script. `_ready`, `_process`, signals, etc.
-			* `/utilities/`: Folder containing utilities for various blocks.
-				* `/background/`: Generates a nice looking background with notches for blocks.
-				* `/drag_drop_area/`: A simple node that signals on mouse down and up
-				* `/parameter_input/`: An input for nodes to receive data from raw text, or from a snapped `ParameterBlock`.
-				* `/snap_point/`: Node that the `DragManager` looks for when trying to snap new blocks.
-		* `/block_canvas/`: Contains the code for the `BlockCanvas` which loads and holds blocks on a canvas. This can generate scripts for block scripts made for Godot `Node`s (which is all of the scripts ATM). Also contains resources for serializing blocks.
-		* `/bsd_templates/`: Template block script data files for loading a default script. E.g. `_ready` and `_process` entry blocks already on canvas.
-		* `/picker/`: Contains the picker scene, and code that generates the blocks that populate the picker.
-			* `/categories/`: Contains `CategoryFactory` which generates the global block list programmatically from template blocks.
-		* `/title_bar/`: Contains the title bar which should display the name of the current script and the node it inherits from.
-* `/addons/gut/`: Code for Godot unit tests.
-* `/addons/plugin_refresher/`: A plugin used to refresh the block_code plugin without having to turn it on and off every time.
-* `/test_game/`: Contains a test game scene with example block code scripts.
-
-
diff --git a/docs/TECH_OVERVIEW.md b/docs/TECH_OVERVIEW.md
new file mode 100644
index 00000000..b9165aa3
--- /dev/null
+++ b/docs/TECH_OVERVIEW.md
@@ -0,0 +1,26 @@
+# Technical Overview
+
+## How to create a new block
+
+Blocks can be created by adding a `BlockDefinition` resource. The global blocks live in resource files under `addons/block_code/blocks/` and are organized in folders by category. You can edit these files in the Godot editor directly, by opening them from the Filesystem Dock. As any other Godot resource, they show up in the Inspector. You can use current ones as reference.
+
+Currently, blocks for custom nodes can't be defined in the same way. They are instead defined programmatically in their GDScript by adding two functions: `func get_custom_class()` and `static func setup_custom_blocks()`. This is expected to be fixed in the future. See the "Simple" nodes provided by this plugin for reference. For example, `addons/block_code/simple_nodes/simple_character/simple_character.gd`.
+
+You don't have to worry for adding blocks for properties setter, getter or "changer". These are generated dynamically in `addons/block_code/code_generation/blocks_catalog.gd`.
+
+## User Interface
+
+The plugin adds a new tab "Block Code" to the editor bottom dock. This contains the `MainPanel` control scene. Which has the following elements:
+	* The `Picker`: Contains the list of blocks organized in categories.
+	* The `BlockCanvas`: Is where placed blocks live. It edits the `BlockScriptSerialization` that generates the code.
+	* The `TitleBar`: Has a dropdown to switch the BlockCode being edited and other controls.
+	* The `DragManager`: Determines how blocks are snapped, and what happens when you drag a block from either the `Picker` or the `BlockCanvas`.
+
+The `DragManager` looks for the closest compatible snap point within a certain range, and if it exists, will show a preview where your `Block` will go if you drop it.
+	* Each `Block` has a `block_type` property, and so does each snap point. They must match to snap.
+	* If a `Block` has the block type `VALUE`, it should have a `variant_type` property (since it represents a value). In that case, it's `variant_type` is considered for snapping along with the snap point's `variant_type`.
+
+The `Block` UI is a regular Godot scene. There is one per each `block_type`. One current discrepancy is that the UI for the `VALUE` block type is called `ParameterBlock`. All others match: eg. for the `CONTROL` type there is a `ControlBlock` scene.
+
+The `BlockCanvas` is filled with blocks as defined in the `BlockScriptSerialization`. When the user interacts with the `BlockCanvas`, the `BlockScriptSerialization` regenerates its GDScript. For instance when the user attaches blocks, or changes the block text input or dropdowns (scene instances of `ParameterInput`).
+

From 77b4b49cceff3bc1a742fc24f2631d0d7d509383 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Manuel=20Qui=C3=B1ones?= <manuel.por.aca@gmail.com>
Date: Wed, 29 Jan 2025 16:15:47 -0300
Subject: [PATCH 2/3] BlockDefinition: Improve editing this resource

Improve editing the BlockDefinition resource in the Inspector:

- Disable fields `variant_type` and `signal_name` when the block type
doesn't correspond.

- Remove `scope` from exports. This is handled internally by the
`DragManager` so can be a regular variable.
---
 .../code_generation/block_definition.gd       | 21 +++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/addons/block_code/code_generation/block_definition.gd b/addons/block_code/code_generation/block_definition.gd
index d13ce8bf..5781733f 100644
--- a/addons/block_code/code_generation/block_definition.gd
+++ b/addons/block_code/code_generation/block_definition.gd
@@ -18,7 +18,8 @@ const FORMAT_STRING_PATTERN = "\\[(?<out_parameter>[^\\]]+)\\]|\\{const (?<const
 @export var category: String
 
 ## Which kind of block is this. See [enum Types.BlockType].
-@export var type: Types.BlockType
+@export var type: Types.BlockType:
+	set = _set_type
 
 ## Only relevant for Value blocks. The variant type that this block is
 ## supposed to return.
@@ -56,9 +57,6 @@ const FORMAT_STRING_PATTERN = "\\[(?<out_parameter>[^\\]]+)\\]|\\{const (?<const
 ## name.
 @export var signal_name: String
 
-## Empty except for blocks that have a defined scope.
-@export var scope: String
-
 ## If checked, the block will be hidden by default in the Picker.
 @export var is_advanced: bool
 
@@ -66,6 +64,9 @@ const FORMAT_STRING_PATTERN = "\\[(?<out_parameter>[^\\]]+)\\]|\\{const (?<const
 ## dynamically add the defaults.
 @export var extension_script: GDScript
 
+## Empty except for blocks that have a defined scope.
+var scope: String
+
 static var _display_template_regex := RegEx.create_from_string(FORMAT_STRING_PATTERN)
 
 
@@ -99,6 +100,18 @@ func _init(
 	is_advanced = p_is_advanced
 
 
+func _set_type(p_type):
+	type = p_type
+	notify_property_list_changed()
+
+
+func _validate_property(property: Dictionary):
+	if property.name == "variant_type" and type != Types.BlockType.VALUE:
+		property.usage |= PROPERTY_USAGE_READ_ONLY
+	elif property.name == "signal_name" and type != Types.BlockType.ENTRY:
+		property.usage |= PROPERTY_USAGE_READ_ONLY
+
+
 func create_block_extension() -> BlockExtension:
 	if not extension_script:
 		return null

From 0030a9aeb129634cec2d3aff25d293bff8d8fee8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Manuel=20Qui=C3=B1ones?= <manuel.por.aca@gmail.com>
Date: Wed, 29 Jan 2025 17:41:11 -0300
Subject: [PATCH 3/3] Improve user documentation

Move it to `docs/USAGE.md`. Split general user guidelines into multiple
sections. Document all Simple nodes that provide high-level abstraction
blocks.

Fix https://github.com/endlessm/godot-block-coding/issues/365
---
 addons/block_code/README.md | 22 +-----------
 docs/USAGE.md               | 72 +++++++++++++++++++++++++++++++++++++
 2 files changed, 73 insertions(+), 21 deletions(-)
 create mode 100644 docs/USAGE.md

diff --git a/addons/block_code/README.md b/addons/block_code/README.md
index 5853fe9e..3073ad88 100644
--- a/addons/block_code/README.md
+++ b/addons/block_code/README.md
@@ -34,11 +34,7 @@ See our [pedagogy and audience documentation](docs/PEDAGOGY.md) for more info.
 
 3. Make sure to enable the plugin in **Project** → **Project Settings** → **Plugins**.
 
-4. You're ready to get started! Open a scene, select a node, and observe that there's a **Block Code** section within the lower central pane of the Godot editor, where you usually find debugging, animation and shader functionality. Click **Block Code** and then use the **Add Block Code** button to create a block canvas.
-
-5. Drag blocks from the picker and snap them together to create a script. You can switch to other Block Code scripts by selecting the respective node from the scene tree.
-
-6. **Run** the scene to see your Block Code scripts in action. Block Code scripts are saved within the scene.
+You're ready to get started! You can continue reading our [user documentation](docs/USAGE.md).
 
 If you clone the plugin's git repository and open it in Godot, you will be presented with a block-built Pong game as an example.
 
@@ -54,22 +50,6 @@ We will now seek feedback from learners, educators and game makers, as well as r
 
 There is no language or data format stability implemented or expected in these early stages. If you upgrade the block coding plugin within an existing project, expect any existing block scripts to stop working and need reimplementing from scratch. For now, you probably want to avoid updating the plugin within your project if it's meeting your needs, or only doing that very sporadically. We will consider offering stability guarantees in future stages of development.
 
-## General user guidance
-
-Block scripts run against the node where you created them. The "Queue Free" block is going to free that node, not any other.
-
-The selection of available blocks varies based on the node type. For example, create a block script on an `Area2D` and you will notice that you have an `On body entered` signal handling block available. Create a node script on an `AnimationPlayer` node and you will observe blocks for starting and stopping animations.
-
-If you wish to switch context to another node, you need to define a function in that other node, and then call it. Once execution jumps into that function, blocks will now act against that other node, and you'll have access to type-specific blocks belonging to that other node. You'll need do this kind of thing if you want to trigger the freeing of another node, or trigger an animation to start playing. This is both strong in conveying the concepts of objects and encapsulation, while also a bit tedious - we may revisit in future!
-
-We have some high level blocks for simplifying common game elements. Add a SimpleCharacter node to get a game element that can be connected to keyboard and gamepad input with just one type-specific block. Add a SimpleScoring node to display a score on-screen, accompanied by simple blocks for adjusting that score.
-
-Lean into animations! Godot's animations functionality goes beyond just simple animations of graphics. You can do so much by combining block coding with Godot's powerful animations editor.
-
-If you want to access the node's property, you can drag the property from the Inspector dock and drop it into the block script as a getter block. And, if you want to modify the property's value, please press & hold Ctrl key when you drop the property, then it will be a setter block of the property in the block script.
-
-You can also drag a file from the Resource Filesystem dock and drop it into the block script as a getter block. It will become a constant value block holding the file's resource full path.
-
 ## Feedback & Discussion
 
 Please join our [Discussion Board](https://github.com/endlessm/godot-block-coding/discussions) to provide feedback, share ideas, and ask questions about building your games with Block Coding.
diff --git a/docs/USAGE.md b/docs/USAGE.md
new file mode 100644
index 00000000..9f1046ac
--- /dev/null
+++ b/docs/USAGE.md
@@ -0,0 +1,72 @@
+# User Documentation
+
+## Adding Block Code to a Node
+
+1. Open a scene, select a node, and observe that there's a **Block Code** section within the lower central pane of the Godot editor, where you usually find debugging, animation and shader functionality. Click **Block Code** and then use the **Add Block Code** button to create a block canvas.
+
+2. Drag blocks from the picker and snap them together to create a script. You can switch to other Block Code scripts by selecting the respective node from the scene tree.
+
+3. **Run** the scene to see your Block Code scripts in action. Block Code scripts are saved within the scene.
+
+Block scripts run against the node where you created them. The "remove" block is going to remove that node, not any other.
+
+The selection of available blocks varies based on the node type. For example, create a block script on an `Area2D` and you will notice that you have an `when this node collides with (something)` signal handling block available. Create a node script on an `AnimationPlayer` node and you will observe blocks for starting and stopping animations.
+
+## Communicating Code Blocks
+
+The "Communication" category provides blocks for this.
+
+To communicate two nodes A and B:
+
+1. Add Block Code to B. Add a `define method (method_name)` entry block in B. Choose a descriptive name and remember it.
+
+2. Add Block Code to A. Add a `call method (method_name) on node (node)` and snap it where needed.
+
+3. Still in the Block Code for A, use the single block under category "Communication | Nodes" for referencing nodes. From the dropdown, select node B.
+
+You can also communicate with multiple nodes at the same time:
+
+1. Add `define method (method_name)` entry block to the target nodes.
+
+2. Add the target nodes to a group. You can do this directly from the Nodes -> Groups dock. Or you can do it dynamically using blocks `add to group (group)` and `remove from group (group)`.
+
+3. In a Block Code, add `call method (method_name) in group (group)`.
+
+From above, you can see that if you wish to switch context to another node, you first need to define a function in that other node, and then call it. Once execution jumps into that function, blocks will now act against that other node, and you'll have access to type-specific blocks belonging to that other node. You'll need to do this kind of thing if you want to e.g. trigger the removal of another node, or trigger an animation to start playing. This is both strong in conveying the concepts of objects and encapsulation, while also a bit tedious - we may revisit in the future!
+
+## High Level Blocks
+
+We have some high level blocks for simplifying common game elements.
+
+* Add a **SimpleCharacter** node to get a game element that can be connected to keyboard and gamepad input with just one type-specific block.
+
+* Add a **SimpleScoring** node to display a score on-screen, accompanied by simple blocks for adjusting that score.
+
+* Add a **SimpleSpawner** node to spawn other scenes, with blocks for controlling the spawn emition and period.
+
+* Add a **SimpleEnding** node for displaying "You win" or "Game over" in the screen with one type-specific block.
+
+## Changing or getting any node property
+
+Common properties like `Node2D.position` have blocks ready to be used in the picker. But (almost) any property that appears in the Inspector can be used in blocks through drag & drop:
+
+1. Open the Block Code at the lower central pane, if not already opened.
+
+2. In the Scene tree, select the Block Code parent node. The editor should now show its properties in the Inspector and the block canvas at the same time.
+
+3. To access a node's property, drag the property label from the Inspector dock and drop it into the block canvas. This will create a block representing its value. You can then snap this value block into other blocks.
+
+4. To modify the property's value, start dragging as above but press & hold Ctrl key while dropping. This will create a `set ... to (value)` block for the property.
+
+## Referencing files in blocks
+
+Some blocks require a file path as parameter. The `load file (file_path) as sound` is one such case. You can use drag & drop to avoid typing the file path:
+
+1. Drag a file from the Filesystem dock and drop it into the block canvas. It will become a constant value block holding the file's resource full path.
+
+2. Then drag the new block to the parameter slot that requires a file path.
+
+## Other suggestions
+
+Lean into animations! Godot's animations functionality goes beyond just simple animations of graphics. You can do so much by combining block coding with Godot's powerful animations editor.
+