diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..806080d --- /dev/null +++ b/Makefile @@ -0,0 +1,50 @@ +#!/bin/make +CORE=$(shell pwd) +DOCSCONF=$(COREDIR)/mkdocs.yml +DOCSOUT=$(COREDIR)/docs_out +TESTPROJECT=/tmp/core_devproject + +dist: help +help: + @echo "Available tasks: docs-deps (installs the docs builder and addons)" + @echo " docs-serve (starts development server)" + @echo " docs-build (export prod ready documentation as html)" + @echo " docs-clean (removes the built documentation)" + @echo " mkdevprj (creates a dev project for development)" + @echo " rmdevprj (removes the dev project)" +docs-deps: + @echo ":: Installing documentation dependencies" + @echo " This may take a few minutes" + @pip install -r requirements.txt +docs-serve: + @echo ":: Serving documentation, press CTRL+C to exit" + # prevent make from terminating + @bash -c "mkdocs serve --dirtyreload --config-file "$(DOCSCONF)";exit 0" +docs-build: + @make docs-clean + @echo ":: Building documentation" + @mkdocs build --site-dir "$(DOCSOUT)" --config-file "$(DOCSCONF)" +docs-clean: + @echo ":: Removing built documentation" + @rm -rf "$(DOCSOUT)" +mkdevprj: + @echo ":: Creating development project" + @mkdir -p $(TESTPROJECT) + @echo -e "config_version=5\n[application]\nconfig/name=\"CORE development project\"\nrun/main_scene=\"res://CORE/coreinit.tscn\"\nconfig/use_custom_user_dir=true\nconfig/custom_user_dir_name=\"core_devproject\"\nconfig/features=PackedStringArray(\"4.1\", \"GL Compatibility\")\nboot_splash/bg_color=Color(0, 0, 0, 1)\nboot_splash/show_image=false\nconfig/icon=\"res://CORE/soscore.png\"\n[autoload]\nLogger=\"*res://CORE/logger.gd\"\nPreprocessor=\"*res://CORE/preprocessor.gd\"\n[display]\nwindow/size/viewport_width=960\nwindow/size/viewport_height=540\n[rendering]\nrenderer/rendering_method=\"gl_compatibility\"\nrenderer/rendering_method.mobile=\"gl_compatibility\"" > "$(TESTPROJECT)/project.godot" + @echo -e "extends Node\n\n@onready\nvar core = get_node(\"/root/core\")\n\nfunc _ready() -> void:\n core.welcome()" > "$(TESTPROJECT)/init.gd" + @echo -e "extends Node\nvar core_startscript = \"res://init.gd\"\nvar wmgr_size_x = 960\nvar wmgr_size_y = 540\nvar wmgr_title = \"CORE development project\"\nvar wmgr_mode = 0\nvar splash_enabled = false\nvar splash_image = \"res://CORE/soscore.png\"\nvar splash_image_size = 256\nvar splash_color = \"000000\"" > config.gd + @ln -s $(CORE) $(TESTPROJECT)/CORE + @echo ":: Development project created." + @echo " You can now launch Godot and open '$(TESTPROJECT)'." + @echo " Don't forget to save and execute 'make rmdevprj' when you're finished." +rmdevprj: + @echo ":: Removing development project" + @echo ":: Killing all open programs" + @bash -c "lsof | grep '$(TESTPROJECT)'||exit 0 | awk '{print $2}'||exit 0 | xargs kill||exit 0;exit 0" &> /dev/null + @echo ":: Removing directory" + @rm -rf $(TESTPROJECT) + @rm -rf config.gd + @echo ":: Removing .import files" + @bash -c "rm -rf *.import||exit 0;exit 0" + @echo ":: Removing 'uid://' strings" + @bash -c "for file in *.tscn; do cat \"\$$file\"|sed -E 's/\ uid=\"[^\"]*\"//g'|tee \$$file;done &> /dev/null" diff --git a/README.md b/README.md index 63f1eb5..1f74cbf 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -

+

SOSCore icon

# StarOpenSource CORE (aka. SOSCORE aka. CORE) SOSCORE/CORE is a framework that simplifies development for games and applications made in Godot 4. @@ -6,16 +6,16 @@ SOSCORE/CORE is a framework that simplifies development for games and applicatio # Development status CORE is under heavy development and can be very unstable. Please do not use CORE in conjunction with your game/application for now (except if you want to debug your game 24/7 and read a lot of gdscript files). -# Roadmap to release +# Roadmap to release :blobfoxbongo: - Mod loading system - Notification API - Basic debugging tool (CTRL+C to crash, F3 to toggle statistics) -- Better documentation (docs4everything) +- ~~Better documentation (docs4everything)~~ - Everything commented and explained - Documentation page explaining what does what (for CORE noobies) - ~~Autoload singleton check removal~~ - More wmgr functions -- Website +- ~~Website~~ - ~~Silencing startup messages (info -> diag)~~ - ~~Remove autoload component~~ - ~~Fix syntax (set return types missing)~~ diff --git a/count_characters.sh b/count_characters.sh new file mode 100755 index 0000000..dac6967 --- /dev/null +++ b/count_characters.sh @@ -0,0 +1,36 @@ +#!/bin/bash +function dircount() { + if [ "$VERBOSE" == "true" ]; then echo ":: Checking directory \"$*\"..."; fi + cd "$*" || exit 54 + for file in $FILEEXTENSION; do + export "file_full=$*/$file" + if [ -d "$file" ]; then + dircount "$file_full" + elif [ -f "$file" ]; then + if [ "$IGNORE_SCRIPT" == "true" ] && [ "$file" == "count_characters.sh" ]; then + if [ "$VERBOSE" == "true" ]; then echo ":: Skipping this script"; fi + else + if [ "$VERBOSE" == "true" ]; then echo ":: Counting characters in file \"$file_full\"..."; fi + export "COUNT_FILE=$(wc -m < "$file_full")" + export "COUNT=$((COUNT + COUNT_FILE))" + fi + else + if [ "$VERBOSE" == "true" ]; then echo ":: Skipping \"$file_full\" (no file or directory)"; fi + fi + done + cd .. +} +if [ "$FILEEXTENSION" == "" ]; then + export "FILEEXTENSION=*" +fi +if [ "$*" == "" ]; then + dircount "$(pwd)" +else + dircount "$(pwd)/$*" +fi +if [ "$VERBOSE" == "true" ]; then echo ""; fi +if [ "$NUMBER_ONLY" == "true" ]; then + echo "$COUNT" +else + echo "Characters counted: $COUNT" +fi diff --git a/docs/favicon.png b/docs/favicon.png new file mode 100644 index 0000000..bb100d8 Binary files /dev/null and b/docs/favicon.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..3f1b224 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,27 @@ +--- +hide: + - navigation +--- +# Home +Welcome to the StarOpenSource documentation! Look below for more information about CORE and code references. + +## What, why, wtf? +The **StarOpenSource CORE Framework** (also known as **CORE** or **SOSCORE**) is a framework that makes the development of games and applications written in **Godot 4.0 and 4.1** easier. CORE implements useful & common functions *(such as calculating the current FPS)* and provides a logging system that even supports formatting, a scene manager and so much more. + +## Can I use CORE in my existing project? +In theory, yes. But if you don't want to refactor a large part of your codebase, don't install CORE. + +## Can I use CORE in my project freely? +[Click this text to learn more about licensing.](/licensing/) + +## I have a problem with CORE! +First of all, read the [Troubleshooting guide](/troubleshooting/). If you can't find your error or it's some incompatibility with CORE and project x, [create a issue](https://git.staropensource.de/StarOpenSource/core/issues/new). + +## How to install/update CORE? +If you want to install CORE, follow [this guide](/install/). If you want to update CORE to the latest version instead, follow [this guide](/update/) instead. + +## Where are the code references? +Look at the [reference index](/refrences/) for a list of all available methods and variables. + +## How can I contact you? +You can contact us by either writing a post in the fediverse and mentioning **[@soscore@net.staropensource.de](https://net.staropensource.de/@soscore)** or writing a email at **[support@staropensource.de](mailto:support@staropensource.de)** diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..70a0ca4 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,68 @@ +--- +hide: + - navigation +--- +# Installing CORE +## Step 1: Downloading the *CORE Manager* +Before we install CORE, we first have to download the **CORE Manager**. It is responsible for installing CORE and downloading updates.
+#### Windows: [CORE-Manager.exe](https://git.staropensource.de/staropensource/core-manager/releases/download/b0/CORE-Manager.exe) +#### Linux: [CORE-Manager.elf](https://git.staropensource.de/staropensource/core-manager/releases/download/b0/CORE-Manager.elf) +#### macOS: Use `wine` to run `CORE-Manager.exe` + +## Step 2: Using the *CORE Manager* +Launch `CORE-Manager.exe` or `CORE-Manager.elf` and type in the path to your Godot project ***(replace backslashes with regular slashes on Windows)***. Click on `Install` and wait until it's finished. + +**Note: If you are updating CORE, click on `Update` instead.** + +## Step 3: Configuring your project +Launch your project in the Godot Editor and go to your project settings. You now need to set your startup scene to `res://CORE/coreinit.tscn`. + +## Step 4: Configuring CORE +Edit the `res://CORE/config.gd` file and set the `core_startscript` variable to a GDScript file. That GDScript file will act as your init script and can be used to load your game. You can find the `config.gd` reference [here](/references/config.gd/). + +## Step 5: Write your init script +Create a new GDScript file and write this into it: +``` gdscript +extends Node + +@onready +var core = get_node("/root/core") #(1)! + +func _ready() -> void: + core.welcome() #(2)! + Logger.enable_diag = true #(3)! + Logger.diag("","This is a diagnostic message. I can only be seen with Logger.enable_diag being true.") + Logger.info("","This is a informational message.") + Logger.warn("","This is a warning message.") + Logger.error("","This is a error message.") + await get_tree().create_timer(0.1).timeout #(4)! + get_tree().quit(0) +``` + +1. Imports the CORE Holder aka. /root/core +2. Makes CORE say hello :) +3. Enables diagnostic log output +4. Waits 100 milliseconds for the log messages to be printed before exiting + +Now replace `` with the filename of your script (without `.gd`) and save it under the path you specified in the `core_startscript` variable. + +## Step 6: Start your project +Start your project and wait until CORE initialized itself. You should see this output in your Godot console (replace `` in your head with the filename of the init script without `.gd`): +``` text +logger -> Initializing Logger +preprocessor -> Initializing Preprocessor +preprocessor -> Delaying initialization by 0.75s +coreinit -> Checking CORE requirements +coreinit -> Constructing coreloader +coreinit -> Injecting coreloader +coreinit -> Switching to COREBackground +(core) [INFO] CORE git-develop welcomes you! + It seems like everything is working :) +() [DIAG] This is a diagnostic message. I can only be seen with Logger.enable_diag being true. +() [INFO] This is a informational message. +() [WARN] This is a warning message. +() [ERROR] This is a error message. +(coreloader) [DIAG] Removing coreloader +``` + +If your project returns about the same output (a few lines omitted) then CORE has been successfully installed. If not, look for your error [here](/troubleshooting/). If you need a example `init.gd` script, [look here](/references/init.gd/). diff --git a/docs/licensing.md b/docs/licensing.md new file mode 100644 index 0000000..5a5712c --- /dev/null +++ b/docs/licensing.md @@ -0,0 +1,25 @@ +--- +hide: + - navigation +--- +# Licensing +## Disclaimer +This documentation page only covers the most important licensing question. If you want to read more about the GNU General Public License Version 3, [read this](https://www.gnu.org/licenses/gpl-faq.html). + +## Note +Under **modified CORE copy** we understand a CORE installation that has been modified in any way (**config.gd** is excluded). If you modified anything else than the **config.gd** file in the **res://CORE/** folder, you have a modified CORE copy. + +## What happens when the license is violated against? +We'll contact the person/organisation doing that. If they won't take it down or can't be contacted, we'll send a cease and desist letter or contact a lawyer. + +## Can I use CORE inside of my proprietary application or game? +No, you are not allowed to do that. Your project must be open source. [Read more...](https://www.gnu.org/licenses/gpl-faq.html#GPLInProprietarySystem) + +## Do I need to publish a modified CORE copy? +If your project is private, no. But if you are publishing or sharing a application/game that uses a modified CORE copy, **you are required** to publish the modified CORE code under the GNU General Public License v3. [Read more...](https://www.gnu.org/licenses/gpl-faq.html#GPLRequireSourcePostedPublic) + +## Can I change the license of my CORE fork? +No, you can't. You are not allowed to do that. [Read more...](https://www.gnu.org/licenses/gpl-faq.html#HeardOtherLicense) + +## Can I sell my CORE fork? +Yes, but you are required to publish the source code under the GNU General Public License version 3. [Read more...](https://www.gnu.org/licenses/gpl-faq.html#GPLCommercially) diff --git a/docs/references/config.gd.md b/docs/references/config.gd.md new file mode 100644 index 0000000..7bbf1a6 --- /dev/null +++ b/docs/references/config.gd.md @@ -0,0 +1,130 @@ +--- +hide: + - navigation +--- +# CORE configuration file (core.config) +The CORE configuration file is located at `res://CORE/config.gd` and is used for configuring CORE behaviour. A full example configuration can be found [here](#example-configuration). + +## CORE +### core_startscript +- type `String` +- default value `res://init.gd` +- description `The initialization script. It is responsible for loading your application and for example displaying a main menu.` + +## Window manager (wmgr) +### wmgr_size_x +- type `int` +- default value `960` +- description `The window size set at startup (x coordinate).` +### wmgr_size_y +- type `int` +- default value `540` +- description `The window size set at startup (y coordinate).` +### wmgr_title +- type `String` +- default value `"Application/Game using CORE"` +- description `The window title set at startup.` +### wmgr_mode +- type `String` +- default value `0` +- description `The window mode set at startup.` +- format `0` = `WINDOWED`, `1` = `MINIMIZED`, `2` = `MAXIMIZED`, `3` = `FULLSCREEN` or `4` = `EXCLUSIVE_FULLSCREEN` + +## Splash screen (splash) +### splash_enabled +- type `bool` +- default value `false` +- description `Displays or hides the splash screen at startup time.` +- format `true` = `displayed` or `false` = `hidden` +### splash_image +- type `String` +- default value `"res://CORE/soscore.png"` +- description `The path to a image, displayed in the center of the splash screen.` +### splash_image_size +- type `float` +- default value `256` +- description `The size of your image. Used for both the x and y coordinates.` +### splash_color +- type `String` +- default value `000000` +- description `The background color.` +- format `AARRGGBB` or `RRGGBB` (`AA` = `alpha`, `RR` = `red`, `GG` = `green` and `BB` = `blue`) + +## Example configuration +This configuration can be found at `res://CORE/config.gd.example`. +``` gdscript +# core.gd.example +# CORE example configuration file +# +# This file is part of StarOpenSource CORE (SOSCORE) +# Made by the StarOpenSource Project and Contributers +# Available in the public domain. +extends Node + +# Hello fellow dev! This is the CORE configuration file. +# This file can be used to customize CORE to your liking. +# You do not need to modify any CORE script as some things +# might break (everything depends on each other). +# Thank you for using CORE :) + + +# CORE +## core_startscript +## Type: String +## Default value: "res://" +## Enter the path to the game/application +## start script. It will be responsible +## for loading your game or application. +var core_startscript = "res://" + +# wmgr (Window Manager) +## wmgr_size_x +## Type: int +## Default value: 960 +## Defines the default window size (x axis) +var wmgr_size_x = 960 +## wmgr_size_y +## Type: Int +## Default value: 540 +## Defines the default window size (y axis) +var wmgr_size_y = 540 +## wmgr_title +## Type: String +## Default value: "Application/Game using CORE" +var wmgr_title = "Application/Game using CORE" +## wmgr_mode +## Type:int +## Default value: 0 +## ID | Mode +## 0 | Windowed +## 1 | Minimized +## 2 | Maximized +## 3 | Fullscreen +## 4 | Exclusive fullscreen +var wmgr_mode = 0 + +# Splash +## splash_enabled +## Type: bool +## Default value: false +## Enables or disables the splash screen at startup. +## Can be manually enabled with core.splash.display() +var splash_enabled = true +## splash_image +## Type: String +## Default value: "res://CORE/soscore.png" +## The path to your image that will be displayed +## in the center of the splash screen. +var splash_image = "res://CORE/soscore.png" +## splash_image_size +## Type: float +## Default value: 256 +## The size of your splash image. Used for both x and y. +var splash_image_size = 256 +## splash_color +## Type: String +## Default value: "000000" +## The splash screen's background color. Do not include +## a "#" at the start. +var splash_color = "000000" +``` \ No newline at end of file diff --git a/docs/references/core.gd.md b/docs/references/core.gd.md new file mode 100644 index 0000000..27cfeda --- /dev/null +++ b/docs/references/core.gd.md @@ -0,0 +1,59 @@ +--- +hide: + - navigation +--- +# CORE Holder (core) +The **CORE Holder** is responsible for... well holding the components. + +## Constants +### version +- type `string` +- description `The CORE version.` +- format ` ` (`` can be either `release`, `prerelease` or `source`. `` is the latest version number) + +## Methods +### welcome() +- returns `void` +- description `Prints a welcome message and the CORE version.` + +## Internal Variables +Do not touch or you will cause breakage. +### locked +- type `bool` +- default value `false` +- description `If true, attach() will reject new components.` +### readycount +- type `int` +- default value `0` +- description `How many components have been fully initialized.` +### readylized +- type `bool` +- default value `false` +- description `If all components have been fully initialized. Is set to true if readycount is equal to the number of components.` + +## Internal functions +Do not call or you will cause breakage. +### attach() +- returns `void` +- description `Attaches a component to the CORE holder` + - argument `type` + - type `String` + - mandatory `yes` + - description `The component type. Can be "config", "wmgr", "smgr", "resmgr", "events" or "splash".` + - argument `component` + - type `none (intended types are "PackedScene" or "Script")` + - mandatory `yes` + - description `The component attach() should add to the SceneTree.` + - argument `do_setup` + - type `bool` + - mandatory `no, default value is true` + - description `If true, creates a new Control and sets the component as a script. Used for Scripts like "smgr.gd" but not for PackedScene's like "splash.tscn".` +### lock() +- returns `void` +- description `Sets the "locked" variable to true.` +### setready() +- returns `void` +- description `Increases "readycount" variable by 1 and checks if "readycount" is equal to the number of components.` + +# Trivia +- The variable [readylized](#readylized) was named like that because a signal called `ready` already exists in `Node` and can therefore not be used as a name. [JeremyStar™](https://git.staropensource.de/JeremyStarTM) then simply appended `lized` from `initialized` to `ready` and `readylized` was born. diff --git a/docs/references/events.gd.md b/docs/references/events.gd.md new file mode 100644 index 0000000..42c710e --- /dev/null +++ b/docs/references/events.gd.md @@ -0,0 +1,96 @@ +--- +hide: + - navigation +--- +# Events (core.events) +The **Events** component makes tracking changes in your application/game easier. + +## Signals +### window_title +- emitted on `window title change` +- argument `window_title` (type `String`) +- argument `previous_window_title` (type `String`) +### window_size +- emitted on `window size change` +- argument `update_coordinate` (type `String`, can be `X`, `Y` or `BOTH`) +- argument `window_size` (type `Vector2i`) +- argument `previous_window_size` (type `Vector2i`) +### window_pos +- emitted on `window position change` +- argument `update_coordinate` (type `String`, can be `X`, `Y` or `BOTH`) +- argument `window_pos` (type `Vector2i`) +- argument `previous_window_pos` (type `Vector2i`) +### logger_all +- emitted on `log output` +- argument `type` (type `String`, can be `"DIAG"`, `"INFO"`, `"WARN"` or `"ERROR"`) +- argument `script` (type `String`) +- argument `message` (type `String`) +### logger_diag +- emitted on `diagnostic log output` +- argument `script` (type `String`) +- argument `message` (type `String`) +### logger_info +- emitted on `informational log output` +- argument `script` (type `String`) +- argument `message` (type `String`) +### logger_warn +- emitted on `warning log output` +- argument `script` (type `String`) +- argument `message` (type `String`) +### logger_error +- emitted on `error log output` +- argument `script` (type `String`) +- argument `message` (type `String`) + +## Internal variables +### window_title_prev +- type `String` +- default value `""` +- description `The previous title.` +### window_size_x_prev +- type `int` +- default value `0` +- description `The previous window size (x coordinate)` +### window_size_y_prev +- type `int` +- default value `0` +- description `The previous window size (y coordinate)` +### window_pos_x_prev +- type `int` +- default value `0` +- description `The previous window position (x coordinate)` +### window_pos_y_prev +- type `int` +- default value `0` +- description `The previous window position (y coordinate)` + +## Internal functions +### _ready() +- returns `void` +- description `connects the logger's "logevent" signal with the "logger_update()" function` +### _process() +- returns `void` +- description `checks for window title, size and position changes and emits a signal if one changes` + - argument `_delta` + - type `float` + - mandatory `yes` + - description `The delta value passed by the engine` +### logger_update() +- returns `void` +- description `emits "logger_all" signal and checks against type and sends the corresponding "logger_" signal` + - argument `type` + - type `String` + - mandatory `yes` + - description `The log type` + - argument `script` + - type `String` + - mandatory `yes` + - description `The script responsible for the log output` + - argument `message` + - type `String` + - mandatory `yes` + - description `The log message` + - argument `_logmessage` + - type `String` + - mandatory `yes` + - description `The printed (processed) log message` diff --git a/docs/references/index.md b/docs/references/index.md new file mode 100644 index 0000000..7e72fe0 --- /dev/null +++ b/docs/references/index.md @@ -0,0 +1,16 @@ +--- +hide: + - navigation +--- +# References index +Here you can find all code references.
+**Index syntax**: *Human-friendly name (callable_gdscript.name)* + +## [CORE configuration file (core.config)](/references/config.gd/) +## [CORE Holder (core)](/references/core.gd/) +## [Events (core.events)](/references/events.gd/) +## [Preprocessor (Preprocessor)](/references/preprocessor.gd/) +## [Resource Manager (core.resmgr)](/references/resmgr.gd/) +## [Scene Manager (core.smgr)](/references/smgr.gd/) +## [Splash Screen (core.splash)](/references/splash.gd/) +## [Window Manager (core.wmgr)](/references/wmgr.gd/) diff --git a/docs/references/preprocessor.gd.md b/docs/references/preprocessor.gd.md new file mode 100644 index 0000000..f765e0c --- /dev/null +++ b/docs/references/preprocessor.gd.md @@ -0,0 +1,219 @@ +--- +hide: + - navigation +--- +# Preprocessor (Preprocessor) +The **Preprocessor** can format text. +## Tags *(these can be used in log messages too!)* +All tags can be escaped by adding `esc_` before the tag name. Example: +```text +Raw: +Output: +``` +### No process `` +- end tag `no` +- description `Disables preprocessing completely. Doesn't even display the prefix.` +- example: +``` text +Raw: This is atest MESSage. +Output: This is atest MESSage. +``` +### Newline `` +- end tag `no` +- description `Makes a newline while respecting the prefix. Is much recommended over "\n".` +- example (with prefix `prefix_`): +``` text +Raw: Very nice message!Here's another message :) +Output: +prefix_Very nice message! + Here's another message :) +``` +### Lowercase `` +- end tag `yes` +- description `Makes your text lowercase.` +- example: +``` text +Raw: Did you FiNd THAT funny? +Output: Did you find thaT funny? +``` +### Uppercase `` +- end tag `yes` +- description `Makes your text uppercase.` +- example: +``` text +Raw: ThiS TeXT should be UPPercaSED +Output: ThiS TeXT SHOULD BE UPPERcaSED +``` +### Camelcase `` +- end tag `yes` +- description `Makes your text camelcase.` +- example: +``` text +Raw: This text should be CamelCased. +Output: This textShouldBeCamelCased. +``` +### Pascalcase `` +- end tag `yes` +- description `Makes your text pascalcase.` +- example: +``` text +Raw: This text should be PascelCased. +Output: This TextShouldBePascelCased. +``` +### Snakecase `` +- end tag `yes` +- description `Makes your text snakecase.` +- example: +``` text +Raw: This text should be SnakeCased. +Output: This text_should_be_snake_cased. +``` +## Variables +### enabled +- type `bool` +- default value `true` +- description `Enables or disables the preprocessor.` +### verbose_logging +- type `bool` +- default value `false` +- description `Makes the log unreadable. Adds about twenty lines to every process() call.` +### tests_enabled +- type `bool` +- default value `true` +- description `Enables or disables preprocessor testing. Recommended to leave enabled as it disables the preprocessor if it's malfunctioning (somehow). Better to have unformatted text than broken text.` +### tests_level +- type `int` +- default value `1` +- description `Controls when test results are displayed. 0 = Never, 1 = On failure, 2 = Always` + +## Methods +### do_tests() +- returns `void` +- description `Performs tests on all preprocessor functions. Very useful for catching bugs while debugging and/or modifying the preprocessor.` + - argument `ignore_flag` + - type `bool` + - mandatory `no, default value is false` + - description `ignores the "tests_enabled" variable if set to true` +### process() +- returns `String` +- description `Formats a message` + - argument `msg` + - type `String` + - mandatory `yes` + - description `The message used for processing` + - argument `prefix` + - type `String` + - mandatory `yes` + - description `The prefix used for newlines` + - argument `pre_msg` + - type `String` + - mandatory `no, default value is ""` + - description `Inserted before the message` + - argument `post_msg` + - type `String` + - mandatory `no, default value is ""` + - description `Inserted after the message` + - argument `exclusion_filter` + - type `Array` + - mandatory `no, default value is []` + - description `Removes specific Strings from the prefix (used in calculating spaces in _newline())` + +## Internal variables +Do not touch these or you will cause breakage. +### tests_executed +- type `bool` +- default value `false` +- description `If tests have been executed already or not.` +### tests_log +- type `String` +- default value `""` +- description `The latest preprocessor testing log.` +### tests_success +- type `int` +- default value `0` +- description `The testing success count. If the value is 12, testing succeeded. If not, something is broken.` + +## Internal Methods +Do not execute these or you will cause breakage. +### _ready() +- returns `void` +- description `Executes do_tests() and imports logger.` +### _newline() +- returns `String` +- description `Processes the tag` + - argument `msg` + - type `String` + - mandatory `yes` + - description `The message used for processing the tag` + - argument `prefix` + - type `String` + - mandatory `yes` + - description `The prefix used for newlines` + - argument `pre_msg` + - type `String` + - mandatory `yes` + - description `Inserted before the message` + - argument `post_msg` + - type `String` + - mandatory `yes` + - description `Inserted after the message` + - argument `exclusion_filter` + - type `Array` + - mandatory `yes` + - description `Removes specific Strings from the prefix (used in calculating spaces)` +### _case_lower() +- returns `String` +- description `Processes the tags` + - argument `msg` + - type `String` + - mandatory `yes` + - description `The message used for processing the tags` +### _case_upper() +- returns `String` +- description `Processes the tags` + - argument `msg` + - type `String` + - mandatory `yes` + - description `The message used for processing the tags` +### _case_camelcase() +- returns `String` +- description `Processes the tags` + - argument `msg` + - type `String` + - mandatory `yes` + - description `The message used for processing the tags` +### _case_pascalcase() +- returns `String` +- description `Processes the tags` + - argument `msg` + - type `String` + - mandatory `yes` + - description `The message used for processing the tags` +### _case_snakecase() +- returns `String` +- description `Processes the tags` + - argument `msg` + - type `String` + - mandatory `yes` + - description `The message used for processing the tags` +### _case() +- returns `String` +- description `Executes all _case_* functions` + - argument `msg` + - type `String` + - mandatory `yes` + - description `The messages passed to all other _case_* functions` +### _escapes() +- returns `String` +- description `It escapes tags` + - argument `msg` + - type `String` + - mandatory `yes` + - description `The message used for processing the tags` +### _noprocess() +- returns `bool` +- description `Checks if the "msg" variable contains ""` + - argument `msg` + - type `String` + - mandatory `yes` + - description `The message used for searching ""` diff --git a/docs/references/resmgr.gd.md b/docs/references/resmgr.gd.md new file mode 100644 index 0000000..3368f9e --- /dev/null +++ b/docs/references/resmgr.gd.md @@ -0,0 +1,70 @@ +--- +hide: + - navigation +--- +# Resource Manager (core.resmgr) +Responsible for loading and unloading resources, even in batches. + +## Methods +### loadres() +- returns `void` +- description `Loads a resource.` + - argument `resource_name` + - type `String` + - mandatory `yes` + - description `The name of the resource. Used when getting or unloading the resource.` + - argument `resource_path` + - type `String` + - mandatory `yes` + - description `The path to the resource.` + - argument `replace` + - type `bool` + - mandatory `no, default value is false` + - description `If a already existing resource should be overridden or not.` +### unloadres() +- returns `void` +- description `Unloads a resource.` + - argument `resource_name` + - type `String` + - mandatory `yes` + - description `The resource name.` +### loadbatch() +- returns `void` +- description `Loads a batch of resources.` + - argument `batch` + - type `Directory` + - mandatory `yes` + - description `A batch of resources to load.` + - format `{"resource_name":"resource_path"}` + - argument `replace` + - type `bool` + - mandatory `no, default value is false` + - description `If a already exiting resource should be overridden or not.` +### unloadbatch() +- returns `void` +- description `Unloads a batch of resources.` + - argument `batch` + - type `Array` + - mandatory `yes` + - description `A batch of resources to unload.` + - format `["resource_name"]` +### getres() +- description `Returns the requested resource or null if not found.` + - argument `resource_name` + - type `String` + - mandatory `yes` + - description `The resource name.` + +## Internal variables +Do not touch or you will cause breakage. +### resources +- type `Directory` +- default value `{}` +- description `All loaded resources` +- format `{"resource_name":loaded_resource} + +## Internal methods +Do not execute or you will cause breakage. +### _ready() +- returns `void` +- description `Executes core.setready(). That's all.` diff --git a/docs/references/smgr.gd.md b/docs/references/smgr.gd.md new file mode 100644 index 0000000..1d2984f --- /dev/null +++ b/docs/references/smgr.gd.md @@ -0,0 +1,137 @@ +--- +hide: + - navigation +--- +# Scene Manager (core.smgr) +Responsible for displaying scenes in order. + +## Overlays +The scene manager uses something called **overlays**. They hold scenes while keeping order. You can think of them like organized collections of scenes *(because they are exactly that)*. There are four **configurable** and one **unconfigurable** overlay. +### Overlay #1 - `debug` +- description `The debug overlay should contain things like a FPS counter, debug menu, etc..` +- configurable `yes` +- more than one scene `yes` +- adding a scene **[add_debug()](#add_debug)** +- removing a scene **[remove_debug()](#remove_debug)** +### Overlay #2 - `cutscene` +- description `The cutscene should contain... well a cutscene.` +- configurable `yes` +- more than one scene `no` +- adding a scene **[add_cutscene()](#add_cutscene)** +- removing a scene **[remove_cutscene()](#remove_cutscene)** +### Overlay #3 - `menu` +- description `The menu overlay should contain multiple menu scenes.` +- configurable `yes` +- more than one scene `yes` +- adding a scene **[add_menu()](#add_menu)** +- removing a scene **[remove_menu()](#remove_menu)** +### Overlay #4 - `game` +- description `The game overlay should contain a game scene. We recommend displaying main menus under the game instead of the menu overlay.` +- configurable `yes` +- more than one scene `no` +- adding a scene **[add_game()](#add_game)** +- removing a scene **[remove_game()](#remove_game)** +### Overlay #5 - `COREBackground` +- description `COREBackground is a unconfigurable overlay responsible for displaying the log and serves as a background if nothing is displayed.` +- configurable `no` +- more than one scene `no` + +## Methods +### add_debug() +- returns `bool` +- description `Adds a PackedScene to the debug overlay.` + - argument `resource_name` + - type `String` + - mandatory `yes` + - description `Used for loading the scene and the loaded scene name.` +### remove_debug() +- returns `bool` +- description `Removes a menu scene from the debug overlay.` + - argument `scene_name` + - type `String` + - mandatory `yes` + - description `Should be the same as the "resource_name" argument used previously in add_debug().` +### add_cutscene() +- returns `bool` +- description `Adds a PackedScene to the cutscene overlay.` + - argument `resource_name` + - type `String` + - mandatory `yes` + - description `Used for loading the scene and the loaded scene name.` +### remove_cutscene() +- returns `bool` +- description `Removes the game scene from the cutscene overlay.` +### add_menu() +- returns `bool` +- description `Adds a PackedScene to the menu overlay.` + - argument `resource_name` + - type `String` + - mandatory `yes` + - description `Used for loading the scene and the loaded scene name.` +### remove_menu() +- returns `bool` +- description `Removes a menu scene from the menu overlay.` + - argument `scene_name` + - type `String` + - mandatory `yes` + - description `Should be the same as the "resource_name" argument used previously in add_menu().` +### add_game() +- returns `bool` +- description `Adds a PackedScene to the game overlay.` + - argument `resource_name` + - type `String` + - mandatory `yes` + - description `Used for loading the scene and the loaded scene name.` +### remove_game() +- returns `bool` +- description `Removes the game scene from the game overlay.` + +## Internal Variables +Do not touch or you will cause breakage. +### ccr +- type `Control` +- default value `null` +- description `The CORE Scene Root.` +### ccr_debug +- type `Control` +- default value `null` +- description `The debug overlay.` +### ccr_debug_names +- type `Array` +- default value `[]` +- description `A collection of all resource names loaded in the debug overlay.` +- Format `["resource_name"]` +### ccr_cutscene +- type `Control` +- default value `null` +- description `The cutscene overlay.` +### ccr_cutscene_inuse +- type `bool` +- default value `null` +- description `Used for checking if a cutscene scene has been loaded already.` +### ccr_menu +- type `Control` +- default value `null` +- description `The menu overlay.` +### ccr_menu_names +- type `Array` +- default value `[]` +- description `A collection of all resource names loaded in the menu overlay.` +- Format `["resource_name"]` +### ccr_game +- type `Control` +- default value `null` +- description `The game overlay.` +### ccr_game_inuse +- type `bool` +- default value `null` +- description `Used for checking if a game scene has been loaded already.` + +## Internal methods +Do not execute these or you will cause breakage. +### _ready() +- returns `void` +- description `Adds the CORE Scene Root, migrates it and executes add_overlays()` +### add_overlays() +- returns `void` +- description `Adds all configurable overlays.` diff --git a/docs/references/splash.gd.md b/docs/references/splash.gd.md new file mode 100644 index 0000000..9e29f12 --- /dev/null +++ b/docs/references/splash.gd.md @@ -0,0 +1,45 @@ +--- +hide: + - navigation +--- +# Splash Screen (core.splash) +The splash screen component allows you to display a "loading screen" whilst hiding log output (COREBackground). + +## Variables +### image +- type `String` +- default value `` +- description `Path to a image, displayed in the center of the splash screen.` +### image_size +- type `float` +- default value `` +- description `The size of your image. Used for both the x and y coordinates.` +### color +- type `String` +- default value `` +- description `The background color.` +- format `AARRGGBB` or `RRGGBB` (`AA` = `alpha`, `RR` = `red`, `GG` = `green` and `BB` = `blue`) + +## Methods +### apply_config() +- returns `void` +- description `Applies the variables "image", "image_size" and "color" to the scene.` +### display() +- returns `void` +- description `Makes the splash screen visible.` +### dissolve() +- returns `void` +- description `Makes the splash screen invisible.` + +## Internal variables +Do not touch or you will cause breakage. +### enabled +- type `bool` +- default value ` +- description `If the splash screen module should be displayed at CORE startup or not.` + +## Internal methods +Do not execute or you will cause breakage. +### _ready() +- returns `void` +- description `Executes apply_config() and executes display() if "enabled" is true.` diff --git a/docs/references/wmgr.gd.md b/docs/references/wmgr.gd.md new file mode 100644 index 0000000..d2c8bb5 --- /dev/null +++ b/docs/references/wmgr.gd.md @@ -0,0 +1,125 @@ +--- +hide: + - navigation +--- +# Window manager (core.wmgr) +Responsible for managing the main window. + +## Modes +The window can be in one of five different modes. Those are: +### `WINDOWED` +A floating window. +### `MINIMIZED` +Minimizes the window to the taskbar/application list/etc.. +### `MAXIMIZED` +Maximizes the window. +### `FULLSCREEN` +Hides all decorations and sets the window size to the screen size. Has multi-window support. +### `EXCLUSIVE_FULLSCREEN` +Same as the `FULLSCREEN` mode but has way less overhead at the cost of loosing multi-window support. Has different effects on different platforms:
+**Windows**: *Depending on the video driver, the screen might black out for a few seconds.*
+**macOS**: *Prevents the dock and menu from showing up when hovering over the edge of the screen.*
+**Linux/BSD**: *Disables compositing (transparency effects, window close animation, etc.)* + +## Methods +### set_size() +- returns `void` +- description `Updates the window size.` + - argument `x` + - type `int` + - mandatory `yes` + - description `The new window size (x coordinate).` + - argument `y` + - type `int` + - mandatory `yes` + - description `The new window size (y coordinate).` +### get_size() +- returns `Vector2i` +- description `Returns the window size.` +### set_position() +- returns `void` +- description `Updates the window position.` + - argument `x` + - type `int` + - mandatory `yes` + - description `The new window position (x coordinate).` + - argument `y` + - type `int` + - mandatory `yes` + - description `The new window position (y coordinate).` +### get_position() +- returns `Vector2i` +- description `Returns the window position.` +### set_title() +- returns `void` +- description `Updates the window title.` + - argument `title` + - type `String` + - mandatory `yes` + - description `The new window title.` +### get_title() +- returns `String` +- description `Returns the window title.` +### set_mode() +- returns `void` +- description `Updates the window mode.` + - argument `mode` + - type `String` + - mandatory `yes` + - description `The new window mode.` + - format follows `wmgr modes` +### get_mode() +- returns `String` +- description `Returns the window mode.` +### get_fps() +- returns `float` +- description `Returns the current framerate, also known as FPS or frames per second.` +- format `NUMBER.NUMBER` (if argument `flat` is `false`), `NUMBER` (if argument `flat` is `true`) or `INF` if the frame rate is infinite (can be caused if the physics fps is set too high, "should" never occur) + - argument `flat` + - type `bool` + - mandatory `no, default value is false` + - description `If decimal numbers should be returned or not.` + - format `If "true" decimal numbers will be removed, if "false" not.` +### get_rendertime() +- returns `float` +- description `Returns how long the last frame took to render (render time).` +### get_delta() +- returns `float` +- description `Returns the latest delta value.` + +## Internal variables +Do not touch or you will cause breakage. +### window_size_x +- type `int` +- default value `` +- description `The window size (x coordinate). Used at startup only.` +### window_size_y +- type `int` +- default value `` +- description `The window size (y coordinate). Used at startup only.` +### window_title +- type `String` +- default value `` +- description `The window title. Used at startup only.` +### window_mode +- type `String` +- default value `` +- description `The window mode. Used at startup only.` +- format follows `wmgr modes` +### delta +- type `float` +- default value `0` +- description `The latest delta value passed by the engine.` + +## Internal methods +Do not execute or you will cause breakage. +### _ready() +- returns `void` +- description `Applies config variables.` +### _process() +- returns `void` +- description `Updates the "delta" variable.` + - argument `delta` + - type `float` + - mandatory `yes` + - description `You know what it is.` \ No newline at end of file diff --git a/docs/stylesheets/colors.css b/docs/stylesheets/colors.css new file mode 100644 index 0000000..ea0f4f2 --- /dev/null +++ b/docs/stylesheets/colors.css @@ -0,0 +1,5 @@ +:root { + --md-primary-fg-color: #D60532; + --md-primary-fg-color--light: #D60532; + --md-primary-fg-color--dark: #D60532; +} \ No newline at end of file diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..ebbb698 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,46 @@ +--- +hide: + - navigation +--- +# Troubleshooting CORE +**Warning:** This is a very messy document. Use the table of contents to get to your specified error. If you can't find your problem here, [create a issue](https://git.staropensource.de/staropensource/core/issues/new). + +## Invalid argument issues +### (wmgr) [ERROR] Invalid window mode "``". +[wmgr's set_mode() function](/references/wmgr/#set_mode) recieved a invalid window mode. Only possible options are `"WINDOWED"`, `"MINIMIZED"`, `"MAXIMIZED"`, `"FULLSCREEN"` and `"EXCLUSIVE_FULLSCREEN"`. +### (smgr) [ERROR] Resource is not type of PackedScene +You tried loading something that's not a scene into the SceneTree. Check against what you are loading first! + +## Common errors +### (smgr) [ERROR] Failed adding `` scene: Only one `` scene is allowed +Only one scene can be loaded into the `game` and `cutscene` overlays. Perform a check against the overlay first! [Click here for the smgr reference page](/references/smgr/) +### (smgr) [ERROR] Failed removing `` scene: No `` scene is active +You tried removing a scene in the `game` or `cutscene` overlay, but no scene is loaded in that overlay. Perform a check against the overlay first! [Click here for the smgr reference page](/references/smgr/) +### (smgr) [ERROR] Failed adding `` scene: `` scene with name "``" already exists +You tried loading a scene into the `menu` or `debug` overlay, but another scene with the same name already exists in that overlay. Perform a check against the overlay first! [Click here for the smgr reference page](/references/smgr/) +### (resmgr) [ERROR] Loading "``" failed: Resource is loaded already +You tried loading a resource with the resource manager, but a resource with the same name is loaded already. Perform a check against the resmgr first! [Click here for the resmgr reference page](/references/resmgr/) +### (resmgr) [ERROR] Unloading "``" failed: Resource is not present +You tried unloading a resource that is not loaded. Perform a check against the resmgr first! [Click for the resmgr reference page](/references/resmgr/) +### (resmgr) [ERROR] `` a batch failed: Batch is empty +The resource manager can't process a empty batch. Fill it with some information. [Click for the resmgr reference page](/references/resmgr/) + + +## Startup issues +### coreinit -> CORE only supports Godot ``. Please upgrade/downgrade your Godot Project to ``. +Update or downgrade your Godot version to one that CORE supports. See the [requirements page](/requirements/) for more information. +### coreinit -> The CORE logger is missing in your autoload project settings! +The CORE logger (found at `res://CORE/logger.gd`) is missing from your autoload list. Just add it under the name `Logger` and make sure to check `Global variable`. +### coreinit -> The CORE preprocessor is missing in your autoload project settings! +The CORE preprocessor (found at `res://CORE/preprocessor.gd`) is missing from your autoload list. Just add it under the name `Preprocessor` and make sure to check `Global variable`. +### coreinit -> The CORE configuration file (config.gd) is missing! Please copy the config.gd.example file and rename it to config.gd! +The CORE configuration file is missing. Just copy `config.gd.example` and rename it to `config.gd`. Make sure to update it to your likings. +### coreloader.gd:46 @ _ready(): Resource file not found: res://. +The variable `core_startupscript` in CORE's `config.gd` file is empty or points to a missing script. Either set the variable or create a new initialization script. + +## Impossible errors +**If you somehow encounter one of these errors, [report them immediately please](https://git.staropensource.de/staropensource/core/issues/new).** +### Failed attaching `` to CORE: Invalid component +Failed attaching a CORE component (for example `resmgr`) to the CORE holder (`core.gd`). +### Failed to get window mode: The window mode id "`" is not known to CORE. +Godot reported a window mode that CORE can't handle. Can be caused if the version check is removed and a higher Godot version is used than CORE supports. diff --git a/docs/update.md b/docs/update.md new file mode 100644 index 0000000..2077f11 --- /dev/null +++ b/docs/update.md @@ -0,0 +1,10 @@ +--- +hide: + - navigation +--- +# Updating CORE +Updating CORE is the same process as installing it. Just click on `Update` instead of `Install` in the **CORE Manager**. + +### [Click to visit the installation page](/install/) + +Note for contributers: If the update process changes in the future we just need to update the documentation page instead of the whole documentation. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..1f2da59 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,77 @@ +site_name: CORE Framework +site_url: https://core.staropensource.de +copyright: 'Licensed under the GNU General Public License v3' +repo_url: https://git.staropensource.de/staropensource/core +edit_uri: _edit/develop/docs/ +extra_css: + - stylesheets/colors.css + - https://fs.staropensource.de/roboto.css + - https://fs.staropensource.de/roboto-mono.css +markdown_extensions: + - pymdownx.caret + - pymdownx.mark + - pymdownx.tilde + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.superfences +nav: + - Home: index.md + - Licensing: licensing.md + - Installing: install.md + - Updating: update.md + - Troubleshooting: troubleshooting.md + - References: references/ + - Source code: https://git.staropensource.de/staropensource/core/ +theme: + name: material + logo: https://git.staropensource.de/staropensource/core/raw/branch/develop/soscore_round.png + favicon: favicon.png + language: en + features: + - navigation.instant + - navigation.tabs + - navigation.path + - navigation.prune + - navigation.top + - navigation.footer + - header.autohide + - toc.follow + - announce.dismiss + - content.action.edit + - content.code.copy + - content.code.annotate + - search.suggest + font: false + icon: + repo: fontawesome/brands/git-alt + edit: material/pencil + view: material/eye + palette: + - scheme: slate + primary: custom + toggle: + icon: material/weather-sunny + name: Switch to light mode + - scheme: default + primary: custom + toggle: + icon: material/weather-night + name: Switch to dark mode +extra: + social: + - icon: fontawesome/brands/mastodon + link: https://net.staropensource.de/@soscore + name: '@soscore@net.staropensource.de' + - icon: fontawesome/brands/git-alt + link: https://git.staropensource.de/staropensource/core/ + name: StarOpenSource/core.git + homepage: https://core.staropensource.de +plugins: + - git-revision-date-localized: + enable_creation_date: true + type: datetime + - search: + lang: en diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..3199625 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +mkdocs +mkdocs-material +mkdocs-git-revision-date-localized-plugin