CORE/README.md
2024-05-18 16:39:54 +02:00

199 lines
10 KiB
Markdown

# 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) 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.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
```