|
| 1 | +# Block Programming Plugin |
| 2 | + |
| 3 | +## Data flow/Hierarchy |
| 4 | + |
| 5 | +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". |
| 6 | + * The `MainPanel` contains a block `Picker`, a `NodeBlockCanvas`, a `TitleBar`, and a `DragManager`. |
| 7 | + * 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. |
| 8 | + * The `NodeBlockCanvas` is where placed blocks live, and generates the code from the scene tree of blocks. |
| 9 | + * The `TitleBar` displays some information about the block script. |
| 10 | + * The `DragManager` determines how blocks are snapped, and what happens when you drag a block from either the `Picker` or the `NodeBlockCanvas` |
| 11 | + |
| 12 | +2. When a `BlockCode` node is selected, the `MainPanel` supplies the `Picker`, `NodeBlockCanvas`, and `TitleBar` with the `BlockScriptData` (BSD) attached to the `BlockCode` node you clicked. |
| 13 | + * The `Picker` will be loaded with blocks, and any custom blocks supplied by the parent of the `BlockCode` node you clicked. |
| 14 | + * The `NodeBlockCanvas` will be populated with the block scene tree deserialized from the BSD (`BlockScriptData.block_trees`). |
| 15 | + * The `TitleBar` will be populated with the name of class the script inherits. |
| 16 | + * If the BSD is `null`, it will copy and load the default one. |
| 17 | + |
| 18 | +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 `NodeBlockCanvas`. |
| 19 | + |
| 20 | +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. |
| 21 | + * Each `Block` has a `block_type` property, and so does each snap point. They must match to snap. |
| 22 | + * If a `Block` has the block type `VALUE`, it should have a `variant_type` property (since it represents a value). |
| 23 | + * 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`. |
| 24 | + * Each `ParameterBlock` is a `VALUE` block which has this `variant_type` property. |
| 25 | + |
| 26 | +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. |
| 27 | + * The block script is modified when a block is moved, or a `ParameterInput`'s raw input has been changed. |
| 28 | + * Code is generated whenever you modify the block in `NodeBlockCanvas`. |
| 29 | + |
| 30 | +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. |
| 31 | + |
| 32 | + |
| 33 | +## What's inside? |
| 34 | + |
| 35 | +* `/addons/block_code/`: The main plugin folder. |
| 36 | + * `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. |
| 37 | + * `/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. |
| 38 | + * `/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. |
| 39 | + * `/drag_manager/`: Should be in the `ui` folder, let's fix that. Handles dragging blocks across the canvas and picker. |
| 40 | + * `/inspector_plugin/`: An inspector plugin that adds a button to the inspector on `BlockCode` nodes to open the script. |
| 41 | + * `/instruction_tree/`: A utility script that generates code from a tree of `TreeNode`s. This tree is created by `NodeBlockCanvas` and also recursively by the `Block`s themselves. |
| 42 | + * `/lib/`: Some scripts from GodotTours that label and expose some of the editor Control nodes so they can be interfaced with. |
| 43 | + * `/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. |
| 44 | + * `/types/`: Contains all things related to types in the addon. Types of blocks, casting, and variant to string type conversion. |
| 45 | + * `/ui/`: Contains scenes and scripts for all UI related things. Block templates, `MainPanel`, etc. |
| 46 | + * `main_panel.tscn`: Scene for the main addon window. Holds the `Picker`, `BlockCanvas`, `DragManager`, and `TitleBar` |
| 47 | + * `constants.gd`: Contains various styling and functional constants for the addon. |
| 48 | + * `/blocks/`: Folder that holds all of the scenes for block templates. |
| 49 | + * `/block/`: The base class for all blocks. |
| 50 | + * `/statement_block/`: A block that can generate statements from multiple inputs. |
| 51 | + * `/parameter_block/`: A block that returns a value generated from multiple inputs. |
| 52 | + * `/control_block/`: A block that dictates the control flow of the program based on conditions, like if/else. |
| 53 | + * `/entry_block/`: A block that represents an entry point to the block script. `_ready`, `_process`, signals, etc. |
| 54 | + * `/utilities/`: Folder containing utilities for various blocks. |
| 55 | + * `/background/`: Generates a nice looking background with notches for blocks. |
| 56 | + * `/drag_drop_area/`: A simple node that signals on mouse down and up |
| 57 | + * `/parameter_input/`: An input for nodes to receive data from raw text, or from a snapped `ParameterBlock`. |
| 58 | + * `/snap_point/`: Node that the `DragManager` looks for when trying to snap new blocks. |
| 59 | + * `/block_canvas/`: Contains the code for the `BlockCanvas` which loads and holds blocks on a canvas. Inherited by `NodeBlockCanvas` which can generate scripts for block scripts made for Godot `Node`s (which is all of the scripts ATM). Also contains resources for serializing blocks. |
| 60 | + * `/bsd_templates/`: Template block script data files for loading a default script. E.g. `_ready` and `_process` entry blocks already on canvas. |
| 61 | + * `/node_canvas/`: Deprecated |
| 62 | + * `/node_lsit/`: Deprecated |
| 63 | + * `/picker/`: Contains the picker scene, and code that generates the blocks that populate the picker. |
| 64 | + * `/categories/`: Contains `CategoryFactory` which generates the global block list programmatically from template blocks. |
| 65 | + * `/title_bar/`: Contains the title bar which should display the name of the current script and the node it inherits from. |
| 66 | +* `/addons/gut/`: Code for Godot unit tests. |
| 67 | +* `/addons/plugin_refresher/`: A plugin used to refresh the block_code plugin without having to turn it on and off every time. |
| 68 | +* `/test_game/`: Contains a test game scene with example block code scripts. |
| 69 | + |
| 70 | + |
0 commit comments