StarOpenSource/CORE
StarOpenSource/CORE
2
0
Fork 0
Code Issues Pull requests Releases 1 Activity

Documentation/website release and more

Browse source 
This commit added:
- A website and documentation (two in one) containing a install guide and code references
- Character counting script (count_characters.sh)
- Godot development project support (making a temporary godot project)
- Makefile
This commit is contained in:
JeremyStar™ 2023-07-09 00:16:15 +02:00
parent 3146efeec3
commit 83ea84b9ab
21 changed files with 1248 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
Makefile Normal file
View file

@ -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"

8
README.md
View file

@ -1,4 +1,4 @@
<p align=center><img width=200px height=200px src="https://git.staropensource.de/staropensource/core/raw/branch/develop/soscore.png"/></p>
<p align=center><img width=200px height=200px src="https://git.staropensource.de/staropensource/core/raw/branch/develop/soscore.png" alt="SOSCore icon"/></p>
# 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 <img width=32 src="https://net.staropensource.de/system/custom_emojis/images/000/009/330/static/a87bdcca6bcbb86e.png">
# Roadmap to release <img width=32 src="https://net.staropensource.de/system/custom_emojis/images/000/016/921/static/1696fdec3a625c30.png" alt=":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)~~

36
count_characters.sh Executable file
View file

@ -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

BIN
docs/favicon.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 6.8 KiB

27
docs/index.md Normal file
View file

@ -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)**

68
docs/install.md Normal file
View file

@ -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.<br/>
#### 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("<your_script_name>","This is a diagnostic message. I can only be seen with Logger.enable_diag being true.")
Logger.info("<your_script_name>","This is a informational message.")
Logger.warn("<your_script_name>","This is a warning message.")
Logger.error("<your_script_name>","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 `<your_script_name>` 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 `<your_script_name>` 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 :)
(<your_script_name>) [DIAG] This is a diagnostic message. I can only be seen with Logger.enable_diag being true.
(<your_script_name>) [INFO] This is a informational message.
(<your_script_name>) [WARN] This is a warning message.
(<your_script_name>) [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/).

25
docs/licensing.md Normal file
View file

@ -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)

130
docs/references/config.gd.md Normal file
View file

@ -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"
```

59
docs/references/core.gd.md Normal file
View file

@ -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 `<TYPE> <BUILD>` (`<TYPE>` can be either `release`, `prerelease` or `source`. `<BUILD>` 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.

96
docs/references/events.gd.md Normal file
View file

@ -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_<TYPE>" 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`

16
docs/references/index.md Normal file
View file

@ -0,0 +1,16 @@
---
hide:
- navigation
---
# References index
Here you can find all code references.<br/>
**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/)

219
docs/references/preprocessor.gd.md Normal file
View file

@ -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: <esc_up><esc_np></esc_lo>
Output: <up><np></lo>
```
### No process `<np>`
- end tag `no`
- description `Disables preprocessing completely. Doesn't even display the prefix.`
- example:
``` text
Raw: <up>This is a</up><pa>test</pa><np> MESS<lo>age</lo>.
Output: <up>This is a</up><pa>test</pa> MESS<lo>age</lo>.
```
### Newline `<nl>`
- 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!<nl>Here's another message :)
Output:
prefix_Very nice message!
Here's another message :)
```
### Lowercase `<lo></lo>`
- end tag `yes`
- description `Makes your text lowercase.`
- example:
``` text
Raw: Did <lo>you FiNd THA</lo>T funny?
Output: Did you find thaT funny?
```
### Uppercase `<up></up>`
- end tag `yes`
- description `Makes your text uppercase.`
- example:
``` text
Raw: ThiS Te<up>XT should be UPPer</up>caSED
Output: ThiS TeXT SHOULD BE UPPERcaSED
```
### Camelcase `<ca></ca>`
- end tag `yes`
- description `Makes your text camelcase.`
- example:
``` text
Raw: This <ca>text should be CamelCa</ca>sed.
Output: This textShouldBeCamelCased.
```
### Pascalcase `<pa></pa>`
- end tag `yes`
- description `Makes your text pascalcase.`
- example:
``` text
Raw: This <pa>text should be PascelCa</pa>sed.
Output: This TextShouldBePascelCased.
```
### Snakecase `<sn></sn>`
- end tag `yes`
- description `Makes your text snakecase.`
- example:
``` text
Raw: This <sn>text should be SnakeCa</sn>sed.
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 <nl> 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 <lo></lo> tags`
- argument `msg`
- type `String`
- mandatory `yes`
- description `The message used for processing the tags`
### _case_upper()
- returns `String`
- description `Processes the <up></up> tags`
- argument `msg`
- type `String`
- mandatory `yes`
- description `The message used for processing the tags`
### _case_camelcase()
- returns `String`
- description `Processes the <ca></ca> tags`
- argument `msg`
- type `String`
- mandatory `yes`
- description `The message used for processing the tags`
### _case_pascalcase()
- returns `String`
- description `Processes the <pa></pa> tags`
- argument `msg`
- type `String`
- mandatory `yes`
- description `The message used for processing the tags`
### _case_snakecase()
- returns `String`
- description `Processes the <sn></sn> 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 "<np>"`
- argument `msg`
- type `String`
- mandatory `yes`
- description `The message used for searching "<np>"`

70
docs/references/resmgr.gd.md Normal file
View file

@ -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.`

137
docs/references/smgr.gd.md Normal file
View file

@ -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.`

45
docs/references/splash.gd.md Normal file
View file

@ -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 `<splash_image config variable>`
- description `Path to a image, displayed in the center of the splash screen.`
### image_size
- type `float`
- default value `<splash_image_size config variable>`
- description `The size of your image. Used for both the x and y coordinates.`
### color
- type `String`
- default value `<splash_color config variable>`
- 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 `<splash_enabled config variable>
- 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.`

125
docs/references/wmgr.gd.md Normal file
View file

@ -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:<br/>
**Windows**: *Depending on the video driver, the screen might black out for a few seconds.*<br/>
**macOS**: *Prevents the dock and menu from showing up when hovering over the edge of the screen.*<br/>
**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 `<wmgr_size_x config variable>`
- description `The window size (x coordinate). Used at startup only.`
### window_size_y
- type `int`
- default value `<wmgr_size_y config variable>`
- description `The window size (y coordinate). Used at startup only.`
### window_title
- type `String`
- default value `<wmgr_title config variable>`
- description `The window title. Used at startup only.`
### window_mode
- type `String`
- default value `<wmgr_mode config variable>`
- 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.`

5
docs/stylesheets/colors.css Normal file
View file

@ -0,0 +1,5 @@
:root {
--md-primary-fg-color: #D60532;
--md-primary-fg-color--light: #D60532;
--md-primary-fg-color--dark: #D60532;
}

46
docs/troubleshooting.md Normal file
View file

@ -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 "`<PLACEHOLDER>`".
[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 `<PLACEHOLDER>` scene: Only one `<PLACEHOLDER>` 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 `<PLACEHOLDER>` scene: No `<PLACEHOLDER>` 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 `<PLACEHOLDER>` scene: `<PLACEHOLDER>` scene with name "`<PLACEHOLDER>`" 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 "`<PLACEHOLDER>`" 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 "`<PLACEHOLDER>`" 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] `<Unloading/Loading>` 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 `<PLACEHOLDER>`. Please upgrade/downgrade your Godot Project to `<PLACEHOLDER>`.
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 `<PLACEHOLDER>` 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 "`<PLACEHOLDER`>" 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.

10
docs/update.md Normal file
View file

@ -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/)
<small>Note for contributers: If the update process changes in the future we just need to update the documentation page instead of the whole documentation.</small>

77
mkdocs.yml Normal file
View file

@ -0,0 +1,77 @@
site_name: CORE Framework
site_url: https://core.staropensource.de
copyright: 'Licensed under the <a href="https://git.staropensource.de/StarOpenSource/core/src/branch/develop/LICENSE">GNU General Public License v3</a>'
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

3
requirements.txt Normal file
View file

@ -0,0 +1,3 @@
mkdocs
mkdocs-material
mkdocs-git-revision-date-localized-plugin