Merge pull request #371 from endlessm/high-level-docs

High level docs

Author: wjt

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.

addons/block_code/code_generation/block_definition.gd

@@ -11,27 +11,62 @@ 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
 
-@export var type: Types.BlockType
+## Which kind of block is this. See [enum 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.
 @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
-@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
 
+## Empty except for blocks that have a defined scope.
+var scope: String
+
 static var _display_template_regex := RegEx.create_from_string(FORMAT_STRING_PATTERN)
 
 
@@ -65,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

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 = {

docs/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`).
+