CORE/README.md

# CORE Framework
The CORE Framework aims at simplifying development for developers writing their code in the Godot Engine, version *4.2*.

## Index
- [About](#about)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [Testing](#testing)
- [File structure](#file-structure)

## About
The CORE Framework is written in GDScript (for now, see [#14](https://git.staropensource.de/StarOpenSource/CORE/issues/14)) and acts as the base for your games and applications. It includes a logger w/ crashhandler, scene management system, downloader, miscellaneous stuff and much more. \
Read more about CORE [here](https://core.staropensource.de/about/).

## Documentation
You can read CORE's documentation at [core.staropensource.de](https://core.staropensource.de)

## Contributing
### Requirements
You need the following things to contribute to CORE:
- the latest Godot Editor version (at the time of writing `4.2.1`)
- knowledge of GDScript
- knowledge about unit testing and [Bessere Tests](https://git.staropensource.de/StarOpenSource/BessereTests), our unit testing framework
### Setup
Execute this in your terminal:
```bash
cd /your/project/directory
git clone https://git.staropensource.de/StarOpenSource/CORE.git
cd CORE
git checkout develop  # Don't work on the stable branch
git checkout -b <your username>-patch-1
git remote add upstream $(git remote get-url origin)
git remote remove origin
git remote add origin "https://<your username>:<your access token>@git.staropensource.de/<your username>/CORE.git"
git submodule update --init --recursive
```

Now start the Godot Editor and import CORE.
### Code style
We use the following code style for CORE:
```bash
extends Node

# Please set the type for variables. If a variable can have multiple types, use Variant or Node
var some_string: String = ""
# No value is also valid, unless the type does not accept null (for example integers)
var various_types: Variant
# Please set the containing type for arrays, unless an array can contain multiple types
var some_array: Array[String] = [ "some", "string" ]
# Dictionaries and Arrays must be nicely formatted
var dict_of_fruits: Dictionary = { "fruits": ["apple", "banana", "orange"], "good_fruits": { "apple": "Tastes good, available pretty much everywhere", "orange": "Nice." }, "bad_fruits": { "banana": "Does not taste good." } }

# For duplication example, ignore
var nodes: Array[String] = [ "abc", "def", "ghi", "jkl" ]
var node_abc: Node
var node_def: Node
var node_ghi: Node
var node_jkl: Node

# This is illegal
func _ready() -> void: pass

# Please set the return type for functions
func some_function(test_string: String) -> String:
	return test_string.repeat(5)

# Please, please avoid code duplication. Here's a nice example of what to avoid and how to fix it.
func duplication_bad() -> void:
	node_abc = Node.new()
	node_def = Node.new()
	node_ghi = Node.new()
	node_jkl = Node.new()
	node_abc.name = "Test node 1"
	node_def.name = "Test node 2"
	node_ghi.name = "Test node 3"
	node_jkl.name = "Test node 4"
	add_child(node_abc)
	add_child(node_def)
	add_child(node_ghi)
	add_child(node_jkl)

func duplication_good() -> void:
	var node_num: int = 0
	for node_name in nodes:
		# Use '+=' or '-=' to subtract something from an integer
		counter += 1
		set("node_" + node_name, Node.new())
		get("node_" + node_name).name = "Test node " + str(node_num)
		add_child(get("node_" + node_name))
```

Please note that you may find old code which does not yet follow these code style guidelines. If you find any, please fix them or report them, thank you!
### Committing
Simply use `git add .`, `git commit -m "<a good and meaningful commit message"` and `git push -u origin <your username>-patch-1` to push your changes. Don't forget to create a pull request once you are done. \
If you don't want to do everything from the command line you can use [gitui](https://github.com/extrawurst/gitui). It's a good and easy to use tui git client which I ([JeremyStarTM](https://git.staropensource.de/JeremyStarTM)) personally use and like. You can't do everything from gitui though, so please keep that in mind.

### Testing
CORE uses [Bessere Tests](https://git.staropensource.de/StarOpenSource/BessereTests) for unit testing. Bessere Tests is a dead simple unit testing system for Godot also developed by the StarOpenSource Project. \
To run all tests, execute `/path/to/godot.binary --headless -d -v -s --path . addons/besseretests/src/cmd.gd` in your terminal.

## File structure
Here's a file structure for this project:
```plain
.
├── addons
│   ├── besseretests -> ../dist/submodules/besseretests/addons/besseretests  Symlink to the Bessere Tests submodule
│   └── besseretests_config.gd                                               Bessere Tests configuration file
├── dist
│   ├── build-distrib-assetlibrary.sh                                        Builds a distribution directory for distributing CORE in the Godot Asset Library.
│   ├── build-distrib-git.sh                                                 Builds a distribution directory for distributing CORE using git.
│   ├── core.png
│   ├── core.png.import
│   ├── core.xcf
│   ├── FiraCode
│   │   ├── Bold.ttf
│   │   ├── Bold.ttf.import
│   │   ├── Light.ttf
│   │   ├── Light.ttf.import
│   │   ├── Medium.ttf
│   │   ├── Medium.ttf.import
│   │   ├── Regular.ttf
│   │   ├── Regular.ttf.import
│   │   ├── Retina.ttf
│   │   └── Retina.ttf.import
│   └── submodules                                                           Contains all submodules CORE uses
│       └── besseretests
├── docs                                                                     CORE's documentation, includes a Makefile
│   ├── babel.config.js
│   ├── docs                                                                 Where all documentation pages lie
│   │   ├── about.md
│   │   ├── getting-started                                                  Getting started guide
│   │   │   ├── _category_.json
│   │   │   ├── initializing-core.md
│   │   │   └── setting-up.mdx
│   │   ├── reference                                                        CORE class and module reference
│   │   │   ├── _category_.json
│   │   │   ├── coreconfiguration.md
│   │   │   ├── core.md
│   │   │   ├── coretypes.md
│   │   │   ├── erm.md
│   │   │   ├── loggerinstance.md
│   │   │   ├── logger.md
│   │   │   ├── misc.md
│   │   │   ├── sms.md
│   │   │   └── storage.md
│   │   └── terminology.md
│   ├── docusaurus.config.ts                                                 Documentation configuration
│   ├── Makefile                                                             Makefile for managing the documentation
│   ├── package.json
│   ├── package-lock.json
│   ├── README.md                                                            Explains some Makefile commands you can execute
│   ├── sidebars.ts
│   ├── src
│   │   ├── css
│   │   │   └── custom.css
│   │   └── pages
│   │       ├── index.module.css
│   │       └── index.tsx
│   ├── static
│   │   └── dist
│   │       └── core.png -> ../../../dist/core.png                           Symlink to the framework icon
│   └── tsconfig.json
├── LICENSE
├── project.godot
├── README.md
├── src                                                                      Contains the source code
│   ├── classes
│   │   ├── basemodule.gd
│   │   ├── config.gd
│   │   ├── loggerinstance.gd
│   │   └── types.gd
│   ├── core.gd
│   ├── erm.gd
│   ├── logger.gd
│   ├── logui.gd
│   ├── misc.gd
│   ├── sms.gd
│   └── storage.gd
├── Test.gd                                                                  Test script, only for testing during development
├── tests                                                                    For unit testing
│   ├── test_resources                                                       Scripts, scenes and other resources used in tests
│   │   ├── custom_module.gd                                                 A custom module used in 'tests/unit/core.gd'
│   │   ├── scene.gd                                                         Updates the callback value
│   │   └── scene.tscn                                                       Loads 'scene.gd'
│   ├── unit                                                                 The actual unit tests
│   │   ├── core.gd
│   │   ├── misc.gd
│   │   └── sms.gd
│   └── unitbase.gd                                                          The base for all of our unit tests, includes functions and variables used in all unit tests.
└── Test.tscn                                                                Simply executes `Test.gd`
```