CORE Framework

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

Index

• About
• Documentation
• Contributing
• Testing
• File structure

About

The CORE Framework is written in GDScript (for now) 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.

Documentation

You can read CORE's documentation at 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, our unit testing framework

Setup

Execute this in your terminal:

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:

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. It's a good and easy to use tui git client which I (JeremyStarTM) personally use and like. You can't do everything from gitui though, so please keep that in mind.

Testing

CORE uses Bessere Tests 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:

.
├── 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.xcf
│   ├── FiraCode
│   │   ├── Bold.ttf
│   │   ├── Light.ttf
│   │   ├── Medium.ttf
│   │   ├── Regular.ttf
│   │   ├── Retina.ttf
│   └── submodules                                                           Contains all submodules CORE uses
│       └── besseretests
├── docs                                                                     CORE's documentation
│   ├── babel.config.js
│   ├── docs                                                                 Where all documentation pages lie
│   │   ├── about.md
│   │   ├── getting-started                                                  Getting started guide
│   │   │   ├── _category_.json
│   │   │   ├── initializing-core.md
│   │   │   └── setting-up.mdx
│   │   ├── guides                                                           Various guides for specific stuff
│   │   │   ├── _category_.json
│   │   │   └── custom-modules.md
│   │   ├── reference                                                        CORE class and module reference
│   │   │   ├── _category_.json
│   │   │   ├── classes                                                      Reference for classes
│   │   │   │   ├── basemodule.md
│   │   │   │   ├── _category_.json
│   │   │   │   ├── core.md
│   │   │   │   ├── loggerinstance.md
│   │   │   │   ├── types.md
│   │   │   │   ├── validationschema.md
│   │   │   │   └── validationsingle.md
│   │   │   └── modules                                                      Reference for modules
│   │   │       ├── _category_.json
│   │   │       ├── config.md
│   │   │       ├── erm.md
│   │   │       ├── logger.md
│   │   │       ├── misc.md
│   │   │       ├── sms.md
│   │   │       ├── storage.md
│   │   │       └── validation.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
│   ├── static
│   │   └── dist
│   │       └── core.png -> ../../../dist/core.png                           Symlink to the framework icon
│   └── tsconfig.json
├── LICENSE
├── project.godot
├── README.md
├── src                                                                      Contains the framework source code
│   ├── classes                                                              Contains all classes except for 'Core'
│   │   ├── basemodule.gd
│   │   ├── config.gd
│   │   ├── loggerinstance.gd
│   │   ├── types.gd
│   │   ├── validationschema.gd
│   │   └── validationsingle.gd
│   ├── core.gd
│   ├── erm.gd
│   ├── logger.gd
│   ├── logui.gd
│   ├── misc.gd
│   ├── sms.gd
│   ├── storage.gd
│   └── validation.gd
├── Test.gd                                                                  Dev 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
│   │   ├── erm.gd
│   │   ├── misc.gd
│   │   ├── sms.gd
│   │   ├── storage.gd
│   │   └── validation.gd
│   └── unitbase.gd                                                          The base for all of our unit tests, includes functions and variables used in all unit tests.
└── Test.tscn                                                                Stub class, has script 'Test.gd' attached