diff --git a/README.md b/README.md index c4a235b..97034d5 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,185 @@ -
+# CORE Framework +The CORE Framework aims at simplifying development for developers writing their code in the Godot Engine, version *4.2*. - - CORE Framework - +## Index +- [About](#about) +- [Documentation](#documentation) +- [Contributing](#contributing) +- [Testing](#testing) +- [File structure](#file-structure) -**The framework that simplifies your game/application development** +## 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 ---- +## 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 -patch-1 +git remote add upstream $(git remote get-url origin) +git remote remove origin +git remote add origin "https://:@git.staropensource.de//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 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: + counter += 1 + set("node_" + node_name, Node.new()) + get("node_" + node_name).name = "Test node " + str(node_num) + add_child(get("node_" + node_name)) +``` +### Committing +Simply use `git add .`, `git commit -m "-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 +│   │   │   ├── edl.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 +│   ├── edl.gd +│   ├── logger.gd +│   ├── logui.gd +│   ├── misc.gd +│   ├── sms.gd +│   └── storage.gd +├── Test.gd Test script, only for testing during development +├── tests For unit testing +│   ├── custom_module.gd A custom module used in tests/unit/core.gd +│   ├── unit The actual unit tests that are executed by Bessere Tests +│   │   ├── core.gd +│   │   ├── misc.gd +│   │   └── z_cleanup.gd Ensures all nodes are cleaned up, throws an error otherwise. +│   └── 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` +```