CORE/docs/install.md

134 lines
6.4 KiB
Markdown
Raw Normal View History

---
hide:
- navigation
---
# Installing CORE
## The safe route
### 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/b1/CORE-Manager.exe)
#### Linux: [CORE-Manager.elf](https://git.staropensource.de/staropensource/core-manager/releases/download/b1/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: Write your init script
Create a new GDScript file at `res://init.gd` (can be anything else, but you need to change the `core_initscript` variable accordingly!) and write this into it:
```gdscript
extends Node
@onready
var core = get_node("/root/CORE") #(1)!
@onready
var logger = core.get_module("Logger") #(2)!
func _ready() -> void:
core.welcome() #(3)!
config.logger_diagnostic = true #(4)!
core.reload_config() #(5)!
logger.diag("<your_script_name>","This is a diagnostic message. I can only be seen if diagnostic log messages are enabled.")
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.")
core.exit_safely() #(6)!
```
1. Imports the CORE "module" aka. /root/CORE
2. Imports the CORE's logger implementation
3. Makes CORE say hello :)
4. Overwrites the logger_diagnostic setting temporarily (in memory)
5. Applies all modified settings
6. Tells CORE to shutdown your application safely. Has to do with CORE's logger and Godot.
Now replace `<your_script_name>` with the file path of your script (preferably with `.gd` and without `res://`) and save it under the path you specified in the `core_initscript` variable.
### Step 5: Start your project
Start your project and wait at least 500ms. You should see this output in your Godot console (with a few variations, of course):
```text
coreinit -> "Fixing" busy setting up children issue #(1)!
coreinit -> Bootstrapping CORE
coreinit -> Checking CORE requirements
coreinit -> Loading modules
coreinit -> Constructing modules
coreinit -> Injecting modules
coreinit -> Updating dependency references
coreinit -> Applying configuration to base modules
coreinit -> Initializing base modules
(CORE/core.gd) [INFO] CORE (source 0) welcomes you! #(2)!
It seems like everything is working :)
(init.gd) [DIAG] This is a diagnostic message. I can only be seen if diagnostic log messages are enabled.
(init.gd) [INFO] This is a informational message.
(init.gd) [WARN] This is a warning message.
(init.gd) [ERR!] This is a error message.
(CORE/coreinit.gd) [DIAG] Bootstrapped CORE, exiting. #(3)!
```
1. These messages are printed anyway as CORE's logger implementation is not loaded at that point in time
2. That log messages comes from your init.gd!
3. tldr we enabled diagnostic messages "too fast". if we delayed the config reload by half a second, we wouldn't have seen that message.
If your project returns about the same output then CORE has been successfully installed. If not, look for your error [here](/troubleshooting/). For a quick start guide, [click here](/quickstartguide/)
## YOLOing the install
Do you want to play with fire? Do you like to live at the edge of what's possible? Or are you just a Arch Linux or Gentoo user? If yes, here's a guide on how to manually install and update CORE.
### Note
This install method is **only recommended for devs experienced with CORE, Godot 4 and Git**. We are not responsible if you mess up something and break your project!
### Installing CORE
1. Create your Godot Project and open the project folder in a terminal
2. Execute `git clone https://git.staropensource.de/StarOpenSource/core.git CORE` (even if you're planning/using a git repository already! Do NOT use git submodules!)
3. `cd` into the CORE folder and copy `config.gd.example` and rename it to `config.gd`. You may edit it to your liking now.
4. Create your init script at `[project root]/init.gd` (or some other path, update it in `config.gd` accordingly) and write this into it:
```gdscript
extends Node
@onready
var core = get_node("/root/CORE")
@onready
var logger = core.get_module("Logger")
func _ready() -> void:
logger.info("init.gd","init.gd loaded.")
core.welcome()
core.exit_safely()
```
5. Go back to Godot and set your startup scene to `res://CORE/coreinit.tscn`
6. Launch your project, you should see something like this in your console:
```text
coreinit -> "Fixing" busy setting up children issue
coreinit -> Bootstrapping CORE
coreinit -> Checking CORE requirements
coreinit -> Loading modules
coreinit -> Constructing modules
coreinit -> Injecting modules
coreinit -> Updating dependency references
coreinit -> Applying configuration to base modules
coreinit -> Initializing base modules
(init.gd) [INFO] init.gd loaded.
(CORE/core.gd) [INFO] CORE (source 0) welcomes you!
It seems like everything is working :)
(CORE/coreinit.gd) [DIAG] Bootstrapped CORE, exiting.
```
7. Congrats, you're not a idiot.
### Updating CORE
1. Open your Godot project folder in a terminal
2. `cd` into the CORE folder and create a backup of your `config.gd` file
3. Run `git pull`
4. Check the [breaking commits](/breaking-commits/) documentation page for breaking changes and update your code accordingly
5. Launch your project and look for any issues. If any arise re-check your code for any [breaking commits](/breaking-commits/) or contact us.
### Reverting a update
#### Reverting an update is unsupported and should **only** be used in special cases.
1. Open your Godot project folder in a terminal
2. `cd` into the CORE folder and create a backup of your `config.gd` file
3. Run `git fetch && git checkout <COMMIT>` (replace `<COMMIT>` with whatever commit you want to revert to)
4. Revert all changes made in all commits after. Checking the [breaking commits](/breaking-commits/) page might be useful.