docs: rewrite docs

mieldepoche · Jul 9, 2023 · d2d55b6 · d2d55b6
1 parent 15b5aec
commit d2d55b6
Show file tree

Hide file tree

Showing 39 changed files with 255 additions and 258 deletions.
diff --git a/README.md b/README.md
@@ -1,86 +1,92 @@
-# **Panku Console**
-![](https://badgen.net/badge/Godot%20Compatible/4.0.stable%2B/cyan) ![](https://badgen.net/github/release/Ark2000/PankuConsole)
+![logo](./docs/assets/logo.png)
 
-![logo](docs/assets/title.png)
+---
 
-All-in-One [Godot Engine 4](https://godotengine.org/) runtime debugging tool.
+**Panku Console is a feature-packed real-time debugging toolkit for Godot Engine.** With Panku Console, you can easily interact with your scripts and objects at runtime, whether to cheat, debug, prototype, or just to have fun.
 
-# ✨ **Features**
+Panku Console is designed to be modular and extensible, and it is easy to add and maintain features. It is also designed to be as unobtrusive as possible, so you can use it in your project without worrying about the impact on the final product.
 
-In short, the core function of Panku Console is to dynamically execute some simple expressions while the game is running. Of course, it is much more than that, in fact, Panku Console is a collection of many practical tools. Here is a brief description of its features.
+# Features
 
-✅ **Flexible Multi-window System**. Any windows can be scaled, snapped, dragged and even become an independent os window.
+## Multi-window UI
 
-✅ **Out-of-the-box Developer Console**. No need to define complex commands, enter any expression, execute it and get the result.
+Any windows can be scaled, snapped, collapsed, dragged and even become an independent os window.
 
-✅ **Expression Monitoring**. Create windows to see the results of expressions in real time.
+![ui](./docs/assets/ui.png)
 
-✅ **Quick Key Binding**. Bind expressions to keys for quick cheating.
+## Developer Console
 
-✅ **Popup Notification**. Pop up any message that deserves your attention.
+Allows you to execute arbitrary code at runtime like if you were god.
 
-✅ **Powerful Inspector Generator**. Automatically convert all export properties in your script into an inspector window.
+![console](./docs/assets/console.png)
 
-✅ **History Management**. Manage all your input history, pin or merge history expressions.
+## Native Logger
 
-✅ **Logger System**. Powered by the native file logging system, simple yet powerful.
+View native logs (the same as the editor output panel) in an overlay or a separate window.
 
-![](docs/assets/preview.webp)
+![logger](./docs/assets/logger.png)
 
-# 🧪 **Installation**
+## Data Controller
 
-1. Download [Latest commit](https://github.com/Ark2000/PankuConsole/archive/refs/heads/master.zip) or the stable [Release](https://github.com/Ark2000/PankuConsole/releases) version.
+Automatically convert all export properties in your script into an inspector window.
 
-2. Copy the `addons` folder to your project root directory.
+![data_controller](./docs/assets/data_controller.png)
 
-3. Enable `PankuConsole` in the Godot project addon settings.
+## Expression Monitor
 
-Or if you prefer to use git, you can add this [mirror repo](https://github.com/Ark2000/panku_console) as a submodule in your addons folder.
+Watch the results of expressions in real time.
 
-```bash
-# in your project root directory
-cd addons
-git submodule add https://github.com/Ark2000/panku_console
-```
+![expression_monitor](./docs/assets/expression_monitor.png)
 
+## And More...
 
-For more information about plugin installation, you can visit the corresponding [Godot documentation](https://docs.godotengine.org/en/stable/tutorials/plugins/editor/installing_plugins.html).
+- **History Manager**: view history inputs. 
+- **Keyboard Shortcut**: bind expressions to keys for quick cheating.
+- **Screen Notifier**: display popup messages on the screen.
+- **Texture Viewer**: view textures in real time.
 
-> **Note**: Panku Console only supports Godot version 4.x, and I personally do not plan to provide support for 3.x.
+Since Panku Console is modular, you can easily remove or add features to suit your needs. 
 
-# 📚 **Quick Start**
+![modular](./docs/assets/modular.png)
 
-Panku Console is designed to take advantage of Godot's native features as much as possible, to provide as little API as possible, to reduce the intrusiveness of the project, to allow most of the operations to be done at runtime without causing additional burden for the developer, and to use pure GDScript development to maximize applicability and maintenance efficiency.
+For more detailed information, please read the following:
 
-Panku Console is a collection of many tools, and each tool has its own documentation, so I will not go into details here. If you want to know more about the plugin, you can read the following documents.
+- [Developer Console](./docs/developer_console.md)
+- [Native Logger](./docs/native_logger.md)
+- [Data Controller](./docs/data_controller.md)
+- [Expression Monitor](./docs/expression_monitor.md)
+- [History Manager](./docs/history_manager.md)
+- [Keyboard Shortcut](./docs/keyboard_shortcut.md)
+- [Texture Viewer](./docs/texture_viewer.md)
+- [Misc Commands](./docs/misc_commands.md)
+- [General Settings](./docs/general_settings.md)
 
-**Content:**
+# Installation
 
-- [Interactive Shell](docs/interactive_shell.md)
-- [Built-in Commands](docs/builtin_commands.md)
-- [Expression Monitor](docs/expression_monitor.md)
-- [Expression Shortcut](docs/expression_shortcut.md)
-- [Generating Inspector Panel](docs/generating_inspector_panel.md)
-- [History Manager](docs/history_manager.md)
-- [Logger](docs/logger.md)
-- [FAQ](docs/faq.md)
+1. Download [Latest commit](https://github.com/Ark2000/PankuConsole/archive/refs/heads/master.zip) from Github
 
-> **Note**: if you want to include the plugin in your released game, you may need to make some modifications to avoid players directly accessing internal state.
+2. Copy the `addons` folder to your project root directory
 
-# **Contributors**
+3. Enable this addon within the Godot settings: `Project > Project Settings > Plugins`
 
-Thanks to these nice [people who contributed to this project](https://github.com/Ark2000/PankuConsole/graphs/contributors), you can also participate in ways including but not limited to:
+Or if you prefer to use git, you can add this [mirror repo](https://github.com/Ark2000/panku_console) as a submodule in your addons folder.
 
-1. if you find bugs or have any suggestions, you can submit [Issues](https://github.com/Ark2000/PankuConsole/issues)
+```bash
+# in your project root directory
+cd addons
+git submodule add https://github.com/Ark2000/panku_console
+```
+
+For more information about plugin installation, you can visit the corresponding [Godot documentation](https://docs.godotengine.org/en/stable/tutorials/plugins/editor/installing_plugins.html).
 
-2. if you have questions, you can discuss them in the [Discussion](https://github.com/Ark2000/PankuConsole/discussions)
+> **Note**: Panku Console currently only supports Godot version 4.x, 3.x support is still in progress.
 
-3. You can also [Contribute Code](https://github.com/Ark2000/PankuConsole/pulls) directly to this project, please refer to [Recent Commits](https://github.com/Ark2000/PankuConsole/commits/master) for the specification of commit message or [here](https://www.conventionalcommits.org/en/v1.0.0/#summary)
+# Contribute
 
-See [CONTRIBUTING](CONTRIBUTING.md) for more details.
+Do you want to contribute? Learn more in [the contribution section](./CONTRIBUTING.md).
 
-# **License**
+# License
 
-[MIT License](LICENSE)
+[MIT License](./LICENSE)
 
-Copyright (c) 2022-present, Feo (k2kra) Wu
+Copyright (c) 2022-present, Feo (k2kra) Wu
diff --git a/addons/panku_console/common/module_manager.gd b/addons/panku_console/common/module_manager.gd
@@ -18,8 +18,7 @@ func load_modules():
 		var module:PankuModule = _m
 		module.core = _core
 		module._init_module()
-
-	#print("modules: ", _modules_table)
+		#print("[info] %s module loaded!" % module.get_module_name())
 
 func update_modules(delta:float):
 	for _m in _modules:

diff --git a/docs/assets/.gdignore → docs/.gdignore b/docs/assets/.gdignore → docs/.gdignore
diff --git a/docs/assets/change_key_binding.png b/docs/assets/change_key_binding.png
diff --git a/docs/assets/console.png b/docs/assets/console.png
diff --git a/docs/assets/console_launcher.png b/docs/assets/console_launcher.png
diff --git a/docs/assets/console_mini.png b/docs/assets/console_mini.png
diff --git a/docs/assets/console_window.png b/docs/assets/console_window.png
diff --git a/docs/assets/data_controller.png b/docs/assets/data_controller.png
diff --git a/docs/assets/expression_monitor.png b/docs/assets/expression_monitor.png
diff --git a/docs/assets/general_settings.png b/docs/assets/general_settings.png
diff --git a/docs/assets/history.png b/docs/assets/history.png
diff --git a/docs/assets/history_manager.png b/docs/assets/history_manager.png
diff --git a/docs/assets/key_binding.png b/docs/assets/key_binding.png
diff --git a/docs/assets/keyboard_shortcut.png b/docs/assets/keyboard_shortcut.png
diff --git a/docs/assets/logger.png b/docs/assets/logger.png
diff --git a/docs/assets/logo.png b/docs/assets/logo.png
diff --git a/docs/assets/logo.svg b/docs/assets/logo.svg
diff --git a/docs/assets/modular.png b/docs/assets/modular.png
diff --git a/docs/assets/monitor.png b/docs/assets/monitor.png
diff --git a/docs/assets/preview.webp b/docs/assets/preview.webp
diff --git a/docs/assets/settings.png b/docs/assets/settings.png
diff --git a/docs/assets/texture_viewer.png b/docs/assets/texture_viewer.png
diff --git a/docs/assets/title.png b/docs/assets/title.png
diff --git a/docs/assets/ui.png b/docs/assets/ui.png
diff --git a/docs/builtin_commands.md b/docs/builtin_commands.md
diff --git a/docs/generating_inspector_panel.md → docs/data_controller.md b/docs/generating_inspector_panel.md → docs/data_controller.md
@@ -1,16 +1,14 @@
-# Generating Inspector Generator
+# Data Controller
 
-![](assets/settings.png)
+![](./assets/data_controller.png)
 
-Using inspector generator, you can generate corresponding inspector window directly from one of your registered objects.
+You can generate data controller window directly from available objects. The value of variables can be modified in the data controller window, and also the data controller window will update value of variables in real time, it is a bidirectional data binding.
 
-The plugin provides a simple sample file of inspector generator, located in the `demo` folder, you can play around with it.
+You can create one by simply typing the object expression in [developer console](./developer_console.md). For example, if you typed `current` in developer console and the scene root script contains export variables, a data controller will be automatically created according to the export variables.
 
-The value of variables can be modified in the inspector window, and also the inspector window will update value of variables in real time.
+> A fact worth noting is that the [general settings](./general_settings.md) window(created by `general_settings.open()`) is also generated by data controller.
 
-You can create it via a predefeined object, specifically `console.add_exporter(...) `.
-
-Another point worth noting is that the settings window of REPL console is also generated entirely using this feature.
+## Supported Types
 
 Currently supported types of exported variables are listed as follows.
 
@@ -64,4 +62,8 @@ Currently supported types of exported variables are listed as follows.
 func xxx():
     print("xxx is called")
 
-```
+```
+
+## Related Files
+
+`panku_console/modules/data_controller/*`
diff --git a/docs/developer_console.md b/docs/developer_console.md
@@ -0,0 +1,77 @@
+# Developer Console
+
+![](./assets/console_window.png)
+
+The developer console is a tool that allows you to execute arbitrary GD expressions at runtime. You can bring it up by pressing the `~` key in the game by default. It is very useful for debugging and testing.
+
+The plugin provides a set of predefined objects and they are capable of such as switching full screen, setting game speed, etc. When there is no auto-completion, you can navigate history input by using up and down arrow keys. When there is auto-completion, press the TAB key to fill it automatically. 
+
+> **Note**: This plugin is currently only tested on PC, and has not been tested on mobile platforms.
+
+## What Are Expressions?
+
+In short, an expression is a set of constants, variables or function calls connected by mathematical operators, such as `interactive_shell.open_window()`, `round(sin(2*PI+1.7*4.2+0.6))`, `null`. 
+
+Expressions are implemented independently of GDScript and have nothing to do with the programming language you are currently using. If you want to know more, you can check the corresponding [Godot documentation](https://docs.godotengine.org/en/stable/tutorials/scripting/evaluating_expressions.html?highlight=expression).
+
+> **Note**: Statements like `player.hp = 100` are not expressions. If you want to perform an assignment in an expression, you can use the `set` method of `Object`, for example `player.set("hp", 100)`, which is a legal expression.
+
+## Access Your Objects
+
+By default, the execution environment contains all modules' environment variable, all methods under `@GlobalScope`(such as `print`, `round`, etc.), and some basic class constructors(such as `Vector2()`, `Array()`).
+
+Your **current scene root** (the last child of `get_tree().root`) will be automatically registered and updated as `current` in the expression execution environment. This means that you can access anything in your scene root script directly, which is very convenient.For example, if you have a `player` variable in your scene root script, you can access it directly in the expression by typing `current.player` or `current.player.hp`.
+
+All of your **autoload singletons** will be automatically registered at the beginning in the expression execution environment. For example, if you have an `AudioManager` singleton, you can access it directly in the expression by typing `AudioManager`.
+
+You can also **register your own objects** in the expression execution environment. For example, if you have a `Player` class, you can register it by calling `Panku.gd_exprenv.register_env("player", Player.new())`, and then you can access it directly in the expression by typing `player`. But it's **not recommended** to do this, since it will introduce unnecessary dependencies.
+
+## About Hinting
+
+Any methods or properties in user script that **do not begin with an underscore** will be added to the auto-completion system. Optionally, you can add description information to a method or property by defining a string constant named `_HELP_xxx`, `xxx` stands for the corresponding method or property name. 
+
+For example:
+
+```gdscript
+const _HELP_simple_func = "This is a simple function."
+func simple_func():
+    print("simple func")
+```
+
+The auto-completion is currently limited to a single property or function, which may be improved later.
+
+## Change Key Binding
+
+By default, the developer console is bound to the `toggle_console` action. You can change it in the **input map settings**.
+
+Currently there's a bug in Godot (See https://github.com/godotengine/godot/issues/25865). You have to add a random input action first to update the input map list, then you can change the default key binding by modifying the `toggle_conosle` action.
+
+![](./assets/change_key_binding.png)
+
+## Related Commands
+
+- `interactive_shell.open_window()`
+
+    Open the developer console window.
+
+- `interactive_shell.open_launcher()`
+
+    Open the developer console minimized version, which only contains the input box and auto-completion.
+
+    ![](./assets/console_launcher.png)
+
+- `interactive_shell.set_unified_window_visibility(enabled:bool)`
+
+    Set whether all windows' visibility should keep the same as the developer console window.
+
+- `interactive_shell.set_pause_if_popup(enabled:bool)`
+
+    Set whether the game should pause when the developer console window is opened.
+
+You can change more settings in [general settings](./general_settings.md).
+
+## Related Files
+
+`panku_console/modules/interactive_shell/*`
+
+`panku_console/modules/variable_tracker/*`