From 3c5e69894f4d3b819e0aef34bc4a18218dfe2bde Mon Sep 17 00:00:00 2001 From: Dex Date: Sun, 30 Jun 2024 18:22:43 -0500 Subject: [PATCH] Describe more the project structure (#166) * add more docs * Update OVERVIEW information. Add information about plugin workflow. * Update OVERVIEW. Add table of content. * Update information about overview file * Fix broken link on contribution file * Update documentation readme file. --- CODE_OF_CONDUCT.md | 2 +- CONTRIBUTING.md | 3 + README.md | 4 +- commands/README.md | 3 +- documentation/Collection.md | 11 ++++ documentation/OVERVIEW.md | 112 ++++++++++++++++++++++++++++++++++++ documentation/README.md | 3 + 7 files changed, 134 insertions(+), 4 deletions(-) create mode 100644 documentation/Collection.md create mode 100644 documentation/OVERVIEW.md create mode 100644 documentation/README.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 7c0bb2f..b6b4d3b 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -65,7 +65,7 @@ representative at an online or offline event. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at -Discord, sending a direct message to AnidemDex#6740 or in the Discord server (https://discord.gg/83YgrKgSZX).. +Discord, sending a direct message to AnidemDex#6740 or in the Discord server (https://discord.gg/6HEwxHCTaK). All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 20e48f2..692e9dd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,3 +73,6 @@ Take a look at this [GIT Style guide](https://github.com/agis-/git-style-guide) > **Author note:** > This contribution guideline is based on many other open source projects. We show it as a _guideline_ and not as a _strict rule_ to follow. + +# Project structure +Please refer to [overview](documentation/OVERVIEW.md) file to know the project structure in detail. \ No newline at end of file diff --git a/README.md b/README.md index 7a80b68..e8877ec 100644 --- a/README.md +++ b/README.md @@ -127,7 +127,7 @@ Thanks to the new Godot 4 features, we can make use of the internal documentatio > We are still working on it. Sorry for the inconvenience 🙁 -Some extra documentation is also added on each folder when is relevant (specially tutorials) +Some extra documentation is also added on each folder when is relevant (specially tutorials). See [OVERVIEW](documentation/OVERVIEW.md) file for more information. ### Example scenarios > We are still working on it. Sorry for the inconvenience 🙁 @@ -142,6 +142,8 @@ This plugin is fully open source, feel free to dive into the code and adapt ever If you find a bug, want a new feature or something is not properly explained, please [open a new issue](https://github.com/AnidemDex/Blockflow/issues/new). +You can join us on the discord server https://discord.gg/6HEwxHCTaK to discuss about features and bugs or send me a direct message on X/Twitter `@anidemdex` too. + ## License See [LICENSE](/LICENSE). diff --git a/commands/README.md b/commands/README.md index cd619cc..382ffba 100644 --- a/commands/README.md +++ b/commands/README.md @@ -21,8 +21,7 @@ sequenceDiagram Processor->>+Command: execution_steps.call() Note over Processor, Command: Default execution Note right of Command: Defined function is called - Destroy Processor - Command --x- Processor: command_finished + Command -->>- Processor: command_finished ``` Command itself can tell which path should processor take: ```mermaid diff --git a/documentation/Collection.md b/documentation/Collection.md new file mode 100644 index 0000000..1575e9d --- /dev/null +++ b/documentation/Collection.md @@ -0,0 +1,11 @@ +# Collection + + Collection is a special resource made to hold a group of values. Think about it like a fancy array in an object form. + +We use this specialized class to manipulate their content and know when an action was performed in the object and we don't intent to expose a direct use for this class in the plugin. + +## Collection structure + +Collection aims to be the equivalent of an array of arrays, being an array of collections, a collection of collections, with some structural functions added to it to create a tree-like structure. + +Most (if not all) methods that array used are implemented on this class, and are just a reflection of what those functions does. \ No newline at end of file diff --git a/documentation/OVERVIEW.md b/documentation/OVERVIEW.md new file mode 100644 index 0000000..0b0e173 --- /dev/null +++ b/documentation/OVERVIEW.md @@ -0,0 +1,112 @@ +# Blockflow overview +This files summarizes the plugin behavior and plugin structure. For detailed information about the content of each folder, take a look at their respective `README` files. + + +- [Plugin flow](#plugin-flow) + - [Editor runtime](#editor-runtime) + - [In-game runtime](#in-game-runtime) + - [Processor runtime](#processor-runtime) +- [Folder structure](#folder-structure) + - [`blockflow` folder](#blockflow-folder) + - [`/commands`](#commands) + - [`/core`](#core) + - [`/debugger`](#debugger) + - [`/documentation`](#documentation) + - [`/editor`](#editor) + - [`/command_block`](#command_block) + - [`/inspector`](#inspector) + - [`/playground`](#playground) + - [`/shortcuts`](#shortcuts) + - [`/icons`](#icons) + - [`/script_templates`](#script_templates) + +## Plugin flow + +### Editor runtime + +1. `Blockflow` plugin is activated by the user: + - Godot engine creates `core/plugin_script.gd` (`Blockflow` plugin) instance. + - On creation, plugin creates and holds `BlockEditor` and `CommandRecord` instances, with some inspector tools. +2. `BlockEditor` is added as main screen node, displayed along with `2D` and `3D` scene views. + - `BlockEditor` adds a `TitleLabel`, `CollectionDisplayer`, `Toolbar` and a `CommandList`. + - Toolbar menu items are added during creation time. + - The editor adds itself to a fake "singleton" name in `Engine` as `Blockflow_main_editor`. + - Even if `CollectionDisplayer` display `CommandBlock`s, it doesn't manipulate the collection, is the editor itself which does this task. +3. First time that editor loads or when it doesn't edit any collection, a "welcome" message is displayed and `CommandList` buttons are disabled. +4. When a command is selected (clicked) from `CommandList` it emits a signal that is listened by `BlockEditor`. That signal contains information about the command selected, which is duplicated and added in the current edited collection. +5. When a command is drag from any place (from a `CommandBlock`, `CommandList` or `FileSystem`) drag information is passed to engine: + - If is drop in `CollectionDisplayer`, the data is handled by`BlockEditor` and the command is added/moved to the dropped position. +6. Right-click on any `CommandBlock` will display a menu with some manipulation options that can be applied to the block. + +### In-game runtime +Editor is not meant to be used _in-game_, but many parts of it can be used/replicated in game. + +### Processor runtime +> Processor core functions are not designed to work in editor. Data manipulation in this node, however, is. Many aspects of the processor in editor time are modified by many `EditorInspector` plugins, added by `Blockflow` plugin. + +`CommandProcessor` takes a single `CommandCollection` at time. + +When you play a scene with `CommandProcessor` nodes (and `start_on_ready` is enabled or you call `start`), processor will call the execution steps from the command position passed (being 0, the first command, used) and will repeat this process until there are no more commands left. + +Command flow is determined by the processor, the next/previous steps can be determined by the current executed command. + +## Folder structure + +Plugin's folder structure. We aim to group related files by folder, but when we can't find a place for it at its creation moment, we put the file one level higher until + +### `blockflow` folder +This is the main project folder. It includes general documentation files (like [`README`](README.md)). + +### `/commands` +Contains all command templates bundled with the plugin. + +Not all of these commands are registered (exposed) in CommandRecord. + +### `/core` +Plugin core files. The plugin aims to work isolated as possible, but most (if not all) scripts tends to rely on these files. + +You can find the plugin script here. + +### `/debugger` +Plugin debugger. + +Debugger UI and debugger scripts that are added under Godot's `debugger` tab to debug in-game processors. + +### `/documentation` + +Documentation files. This folder includes this file. + +Even if each script has their own documentation to describe what is their purpose, some extra information can be found in their `README` files and in this folder. + +### `/editor` +Editor folder. + +All Blockflow UI related files lives here, from the main screen to each individual block script. + +#### `/command_block` +Scripts that defines the structure of the basic command block that is seen in editor through `CommandDisplayer`. + +#### `/inspector` +Inspector scripts that defines custom modifications to different classes that are used in this plugin at `EditorInspector`. + +#### `/playground` +Test (playground) scenes to try Blockflow features and debug them in game. + +Some features can't be used in game runtime since they're locked to the editor runtime, so we test those in these playground scenes. + +#### `/shortcuts` +Shortcuts used in the editor, created as `Shortcut` resources to be able to modify and reuse. + +### `/icons` +Plugin icons. All icons are here, in SVG Format, with a specific color and size selection. + +### `/script_templates` +Script templates that are going to be copied to `res://` when plugin loads for the first time. + +These templates should appear when you create a new script of `Command` type. \ No newline at end of file diff --git a/documentation/README.md b/documentation/README.md new file mode 100644 index 0000000..9c804fa --- /dev/null +++ b/documentation/README.md @@ -0,0 +1,3 @@ +Documentation files. + +These files gives a little more extra information about the plugin structure or certain classes that couldn't be covered in their script definition. \ No newline at end of file