diff --git a/docs/docs/about.md b/docs/docs/about.md index 70e3d1b..c3113c8 100644 --- a/docs/docs/about.md +++ b/docs/docs/about.md @@ -14,6 +14,6 @@ If you want to use the CORE Framework in a new project, then your answer is **ye ## Roadmap - [x] Configuration support - [x] Logger implementation -- [ ] HTTP Request helper +- [x] HTTP Request helper - [ ] Mod Loader - [x] Support for custom modules diff --git a/docs/docs/getting-started/_category_.json b/docs/docs/getting-started/_category_.json new file mode 100644 index 0000000..80fe630 --- /dev/null +++ b/docs/docs/getting-started/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Getting started", + "position": 3, + "link": { + "type": "generated-index", + "description": "Helps you get CORE set up in your project." + } +} diff --git a/docs/docs/getting-started/initializing-core.md b/docs/docs/getting-started/initializing-core.md new file mode 100644 index 0000000..0c077e5 --- /dev/null +++ b/docs/docs/getting-started/initializing-core.md @@ -0,0 +1,45 @@ +--- +sidebar_position: 2 +description: CORE needs to be initialized before usage. +--- + +# Initializing CORE +Before you can use the CORE Framework, you'll need to initialize it. + +This example should explain everything: +```gdscript +extends Node + +# CORE Object +var core: Core +# CORE Logger +## Will be defined before _ready() is called +@onready var logger: CoreBaseModule = core.logger + +func _init() -> void: + # Create new CoreConfiguration + var config: CoreConfiguration = CoreConfiguration.new() + # Set logger level to DIAG + config.logger_level = CoreTypes.LoggerLevel.DIAG + # Initialize CORE with custom configuration + core = Core.new(config) + # Initialize CORE with standard configuration + #core = Core.new() + +func _ready() -> void: + # Initialize CORE completely + await get_tree().process_frame # to avoid "setting up nodes" error + get_tree().root.add_child(core) # add CORE Object to SceneTree + await get_tree().process_frame # wait for CORE to initialize completely + + # >>> Your code should start executing here <<<< + + # Print "Hello World!" to console with all possible 'LoggerLevel''s + for type in CoreTypes.LoggerLevel: + if type == "NONE": continue # Exclude "NONE" logger level + type = StringName(type.to_lower()) # Convert to StringName + logger.call(type, "Hello World!") # Call it + + # Test crash + logger.crash("This is a test crash.") +``` \ No newline at end of file diff --git a/docs/docs/getting-started/setting-up.mdx b/docs/docs/getting-started/setting-up.mdx new file mode 100644 index 0000000..8cbcb47 --- /dev/null +++ b/docs/docs/getting-started/setting-up.mdx @@ -0,0 +1,124 @@ +--- +sidebar_position: 1 +--- + +# Setting up + +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +``` + +This helps you install the CORE Framework in the first place. + +## Using the Godot Asset Library +:::note +This will install the CORE Framework without the ability to easily download updates. You will need to look for updates yourself and install the latest version from the Asset Library yourself. If you don't want that hassle, use a [git installation](#using-git) instead. +::: +This will install the latest *stable* version. +1. Open your project in the Godot Editor and click on the **AssetLib** tab +2. Search for `CORE Framework` +3. Click on the first result and hit **Install** +4. Follow the usual asset installation procedure + +## Using git +Using git to manage a CORE installation is a bit harder than [using Godot's Asset Library](#using-the-godot-asset-library), but comes with more advantages. One of them being able to switch branches or trying out experimental features. +:::note +You'll need to all commands in your project root. +::: +### Installing CORE + + +```bash +git clone https://git.staropensource.de/StarOpenSource/CORE.git CORE +``` + + +```bash +git clone https://git.staropensource.de/StarOpenSource/CORE.git CORE +cd CORE +git checkout stable +``` + + +```bash +git submodule add https://git.staropensource.de/StarOpenSource/CORE.git CORE +``` + + +```bash +git submodule add https://git.staropensource.de/StarOpenSource/CORE.git CORE +cd CORE +git checkout stable +``` + + +### Updating CORE + + +```bash +cd CORE +git pull +``` + + +```bash +cd CORE +git pull +``` + + +```bash +cd CORE +git pull origin develop +cd .. +git submodule update +``` + + +```bash +cd CORE +git pull origin develop +cd .. +git submodule update +``` + + +## Changing branches +:::warning +Changing branches can result in errors and missing features. We don't accept issues regarding switching branches, you will be on your own! +::: + + +```bash +cd CORE +git fetch +git checkout stable +``` + + +```bash +cd CORE +git fetch +git checkout develop +``` + + +```bash +cd CORE +git fetch +git checkout stable +cd .. +git submodule update +``` + + +```bash +cd CORE +git fetch +git checkout develop +cd .. +git submodule update +``` + + \ No newline at end of file diff --git a/docs/docs/reference/_category_.json b/docs/docs/reference/_category_.json index 5e8b404..36f796a 100644 --- a/docs/docs/reference/_category_.json +++ b/docs/docs/reference/_category_.json @@ -1,8 +1,8 @@ { "label": "Reference", - "position": 3, + "position": 4, "link": { "type": "generated-index", - "description": "Documentation about CORE's internals" + "description": "CORE Framework module documentation" } } diff --git a/docs/docs/reference/api/_category_.json b/docs/docs/reference/api/_category_.json deleted file mode 100644 index 3d06be6..0000000 --- a/docs/docs/reference/api/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "API", - "position": 1, - "link": { - "type": "generated-index", - "description": "CORE Framework module documentation" - } -} diff --git a/docs/docs/reference/api/misc.md b/docs/docs/reference/api/misc.md deleted file mode 100644 index 32979a2..0000000 --- a/docs/docs/reference/api/misc.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_position: 3 ---- - -# `Miscellaneous` -Miscellaneous functions that don't fit into other modules. - -## Functions -### *void* quit_safely(*int* exitcode = *0*) -:::note[Awaiting required] -Using the `await` keyword is required for this function. -::: -Adds an small extra delay before exiting. Highly recommended over calling `get_tree().quit()` yourself. \ No newline at end of file diff --git a/docs/docs/reference/api/core.md b/docs/docs/reference/core.md similarity index 92% rename from docs/docs/reference/api/core.md rename to docs/docs/reference/core.md index 670f779..ff8bda4 100644 --- a/docs/docs/reference/api/core.md +++ b/docs/docs/reference/core.md @@ -9,7 +9,7 @@ The **CORE Object** is the class you use to initialize the CORE Framework. ### *int* version_release CORE's release number ### *CoreTypes.VersionType* version_type -CORE's release type. See [`CoreTypes.VersionType`](/reference/api/coretypes#versiontype) for more information. +CORE's release type. See [`CoreTypes.VersionType`](/reference/coretypes#versiontype) for more information. ### *int* version_typerelease CORE's typerelease number @@ -27,8 +27,10 @@ Stores the path to CORE's installation directory. ## Functions ### *void* _init(*CoreConfiguration* new_config) Determines the base path, loads the configuration file and initializes all modules. -### *void* register_custom_module(*String* module_name, *CoreBaseModule* module_class) +### *bool* register_custom_module(*String* module_name, *CoreBaseModule* module_class) Registers a custom module. + +Returns `true` if successful. ### *void* unregister_custom_module(*String* module_name) Unregisters a custom module. ### *CoreBaseModule* get_custom_module(*String* module_name) diff --git a/docs/docs/reference/api/coreconfiguration.md b/docs/docs/reference/coreconfiguration.md similarity index 81% rename from docs/docs/reference/api/coreconfiguration.md rename to docs/docs/reference/coreconfiguration.md index 8f9c2f9..ecd8a99 100644 --- a/docs/docs/reference/api/coreconfiguration.md +++ b/docs/docs/reference/coreconfiguration.md @@ -4,15 +4,20 @@ sidebar_position: 5 # `CoreConfiguration` Provides the default configuration for the CORE Framework. +## Note +All settings are variables. -## Variables +## Global ### *bool* headless = *false* Controls CORE's functionality. Renders GUI-related modules useless when set to `true`, which is the recommended behaviour on servers. For CORE's full functionality, set this to `true`. -### *bool* debug_allow = *false* +### *bool* debugging = *false* :::note This will not enable the development mode automatically, only if you're developing on CORE itself. ::: Allows debugging functionality if set to `true`, or not if set to `false`. +### *bool* custom_modules = *false* +Allows or disallows custom modules. +## Logger ### *CoreTypes.LoggerLevel* logger_level = *CoreTypes.LoggerLevel.INFO* I don't have to explain this, do I? ### *bool* logger_colored = *true* @@ -32,9 +37,10 @@ with a newline! ``` ### *int* logger_newlines_sizelimit = *40* The maximum amount of characters than can appear before `%message%` before newlines won't be overriden. Settiing this variable to `-1` disables this behaviour. -### *bool* logui_background = *true* -Determines if the [`LogUI`](/reference/terminology#logui)'s (by default) black background should be visible. +## LogUI +### *bool* logui_enabled = *true* +Determines if [`LogUI`](/terminology#logui) should be visible or not. ### *Color* logui_background_color = *Color.BLACK* -The color the `LogUI` background will have. +The color the `LogUI` background will have. Set to `Color.TRANSPARENT` for a transparent background. ### *int* logui_font_size = *14* The font size the graphical log output should have. \ No newline at end of file diff --git a/docs/docs/reference/api/coretypes.md b/docs/docs/reference/coretypes.md similarity index 70% rename from docs/docs/reference/api/coretypes.md rename to docs/docs/reference/coretypes.md index 5d266bc..c59d3e4 100644 --- a/docs/docs/reference/api/coretypes.md +++ b/docs/docs/reference/coretypes.md @@ -9,4 +9,6 @@ Contains globaly accessible custom enums and types used throughout the CORE Fram ### VersionType RELEASE, RELEASECANDIDATE, BETA, ALPHA ### LoggerLevel -NONE, ERROR, WARN, INFO, VERB, DIAG \ No newline at end of file +NONE, ERROR, WARN, INFO, VERB, DIAG +### SceneType +NONE, DEBUG, CUTSCENE, MENU, MAIN, BACKGROUND \ No newline at end of file diff --git a/docs/docs/reference/edl.md b/docs/docs/reference/edl.md new file mode 100644 index 0000000..b124951 --- /dev/null +++ b/docs/docs/reference/edl.md @@ -0,0 +1,36 @@ +--- +sidebar_position: 7 +--- + +# `Easy DownLoader` +Pulls files from the internet, awaitable and batchable. + +## Functions +### *Dictionary* awaited_request(*String* url, *HTTPClient.Method* method = *HTTPClient.Method.METHOD_GET*, *PackedStringArray* headers = *PackedStringArray([])*, *String* data = *""*) +Requests a file from the internet, awaitable. + +The returned `Dictionary` has the following structure (example): +```gdscript +{ "result": 0, "http_code": 200, "headers": [ "Server": "nginx" ], "body": [], "body_utf8": [] } + ^ ^ ^ ^ ^ + | | | | | + | | | | --------- The body from the server, as a UTF-8 string + | | | ----------------------- The body from the server, as bytes + | | ------------------------------------------------------ A array of headers + | ---------------------------------------------------------------------- The HTTP response code + ------------------------------------------------------------------------------------ Equal to @GlobalScope.Error. If not 0/Error.OK = the request failed +``` +### *Array[Dictionary]* batch_awaited_request(*PackedStringArray* urls, *HTTPClient.Method* method = *HTTPClient.Method.METHOD_GET*, *PackedStringArray* headers = *PackedStringArray([])*, *String* data = *""*) +Requests multiple file from the internet, awaitable. + +The returned `Dictionary`s have the following structure (example): +```gdscript +{ "result": 0, "http_code": 200, "headers": [ "Server": "nginx" ], "body": [], "body_utf8": [] } + ^ ^ ^ ^ ^ + | | | | | + | | | | --------- The body from the server, as a UTF-8 string + | | | ----------------------- The body from the server, as bytes + | | ------------------------------------------------------ A array of headers + | ---------------------------------------------------------------------- The HTTP response code + ------------------------------------------------------------------------------------ Equal to @GlobalScope.Error. If not 0/Error.OK = the request failed +``` diff --git a/docs/docs/reference/api/logger.md b/docs/docs/reference/logger.md similarity index 87% rename from docs/docs/reference/api/logger.md rename to docs/docs/reference/logger.md index 3677562..079f915 100644 --- a/docs/docs/reference/api/logger.md +++ b/docs/docs/reference/logger.md @@ -26,8 +26,11 @@ Prints a informational message Prints a warning message ### *void* error(*String* message) Prints an error message -### *void* crash(*String* message) +### *void* crash(*String* message, *bool* framework_crash = *false*) :::note[Awaiting required] Using the `await` keyword is required for this function. ::: +:::danger +Please do not set `framework_crash` to `true`. Thank you. +::: Handles crashes. Will terminate your game/application immediately. \ No newline at end of file diff --git a/docs/docs/reference/misc.md b/docs/docs/reference/misc.md new file mode 100644 index 0000000..efac4eb --- /dev/null +++ b/docs/docs/reference/misc.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 3 +--- + +# `Miscellaneous` +Miscellaneous functions that don't fit into other modules. + +## Functions +### *void* quit_safely(*int* exitcode = *0*) +:::note[Awaiting required] +Using the `await` keyword is required for this function. +::: +Adds an small extra delay before exiting. Highly recommended over calling `get_tree().quit()` yourself. +### *float* byte2mib(*int* bytes, *bool* flatten = *true*) +Converts a number of bytes to mebibytes. + +If `flatten` is set to `true`, the decimal part will be discarded. +### *float* mib2byte(*float* mib, *bool* flatten = *true*) +Converts a number of mebibytes to bytes. + +If `flatten` is set to `true`, the decimal part will be discarded. +### *float* mib2gib(*float* mib, *bool* flatten = *true*) +Converts a number of mebibytes to gibibytes. + +If `flatten` is set to `true`, the decimal part will be discarded. +### *float* gib2mib(*float* gib, *bool* flatten = *true*) +Converts a number of gibibytes to mebibytes. + +If `flatten` is set to `true`, the decimal part will be discarded. \ No newline at end of file diff --git a/docs/docs/reference/sms.md b/docs/docs/reference/sms.md new file mode 100644 index 0000000..ffd0583 --- /dev/null +++ b/docs/docs/reference/sms.md @@ -0,0 +1,39 @@ +--- +sidebar_position: 6 +--- + +# `Scene Management System` +Handles scenes and their order. + +## Functions +### *bool* add_scene(*String* sname, *CoreTypes.SceneType* type, *Node* sclass) +Adds a scene to some scene collection. + +Returns `true` if successful. +### *bool* remove_scene(*String* sname, *bool* force_remove = *false*) +:::danger +Please do not set `force_remove` to `true`. Thank you. +::: +Removes a scene from some scene collection. + +Returns `true` if successful. +## *Node* get_scene(*String* sname) +Returns a scene from some scene collection. + +Returns `null` if no scene with that name was found. +## *Node* get_scene_collection(*CoreTypes.SceneType* type) +:::danger +NEVER change a scene collection's properties or free it! You can CRASH the CORE Framework easily by doing this! +::: +:::danger +NEVER free a scene yourself! You can CRASH the CORE Framework easily by doing this! +::: +Returns a scene collection node. Useful if you want to change the node's position or want direct access to one. +## *Array[Node]* get_scene_collection_list(*CoreTypes.SceneType* type) +Returns a list of all loaded scenes in some scene collection. +## *int* get_scene_collection_count(*CoreTypes.SceneType* type) +Returns the number of loaded scenes in some scene collection. +## *CoresTypes.SceneType* exists(*String* sname) +Returns the scene collection a scene is loaded in. + +Returns `CoreTypes.SceneType.NONE` if no scene with that name has been found. \ No newline at end of file diff --git a/docs/docs/reference/terminology.md b/docs/docs/reference/terminology.md deleted file mode 100644 index ecd3619..0000000 --- a/docs/docs/reference/terminology.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Terminology -You don't know a word? Look it up here. - -## CORE Object aka. `CORE` -The **CORE Object** is the class you use to initialize the CORE Framework. -## `LogUI` -Displays the log/console output graphically in the background. \ No newline at end of file diff --git a/docs/docs/terminology.md b/docs/docs/terminology.md new file mode 100644 index 0000000..ce83f9a --- /dev/null +++ b/docs/docs/terminology.md @@ -0,0 +1,15 @@ +--- +sidebar_position: 2 +--- + +# Terminology +You don't know a word? Look it up here. + +## CORE Object aka. `CORE` +The **CORE Object** is the class you use to initialize the CORE Framework. +## `LogUI` +Displays the log/console output graphically in the background. +## `EDL` +Stands for **Easy DownLoader** and allows you to download stuff. +## `SMS` +No, it does not stand for **Short Message Service**, but for **Scene Management System**. It manages your scenes. \ No newline at end of file diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index eef3584..44c14dc 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -115,7 +115,7 @@ const config: Config = { ], markdown: { - format: "md", + format: "detect", mermaid: false, },