changed docs folder name
This commit is contained in:
Will Stuckey
361
environment/LIBRARY_MANAGEMENT.md
Normal file
361
environment/LIBRARY_MANAGEMENT.md
Normal file
@@ -0,0 +1,361 @@
|
||||
# Godot C# Library Management with Git Submodules
|
||||
|
||||
## Overview
|
||||
|
||||
Manage reusable C# libraries across multiple Godot projects using Git submodules. Each library is a separate repository that game projects include as submodules.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
~/GameDev/
|
||||
├── Godot/ # Engine installation
|
||||
├── libraries/ # Local library development
|
||||
│ ├── utilities/
|
||||
│ ├── audio-manager/
|
||||
│ └── ui-framework/
|
||||
└── projects/ # Game projects
|
||||
├── test-game/
|
||||
│ └── Libraries/ # Git submodules
|
||||
│ ├── utilities/
|
||||
│ └── audio-manager/
|
||||
└── puzzle-game/
|
||||
└── Libraries/
|
||||
└── utilities/
|
||||
```
|
||||
|
||||
**Git Organization:**
|
||||
- `library/` org - Reusable libraries
|
||||
- `project/` org - Game projects
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Godot v4.5.1+ (C# support)
|
||||
- .NET 8.0+
|
||||
- Git with Gitea access
|
||||
- Gitea organizations: `library` and `project`
|
||||
|
||||
## Create a Library
|
||||
|
||||
### 1. Initialize Repository
|
||||
|
||||
```bash
|
||||
cd ~/GameDev/libraries
|
||||
git init utilities
|
||||
cd utilities
|
||||
mkdir -p Scripts
|
||||
```
|
||||
|
||||
### 2. Configure Library
|
||||
|
||||
**project.godot:**
|
||||
```ini
|
||||
[application]
|
||||
config/name="Utilities Library"
|
||||
config/features=PackedStringArray("4.3", "C#", "Forward Plus")
|
||||
|
||||
[dotnet]
|
||||
project/assembly_name="EinSoftworks.Utilities"
|
||||
```
|
||||
|
||||
**Utilities.csproj:**
|
||||
```xml
|
||||
<Project Sdk="Godot.NET.Sdk/4.3.0">
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net6.0</TargetFramework>
|
||||
<EnableDynamicLoading>true</EnableDynamicLoading>
|
||||
<RootNamespace>EinSoftworks.Utilities</RootNamespace>
|
||||
<AssemblyName>EinSoftworks.Utilities</AssemblyName>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
### 3. Add Code
|
||||
|
||||
**Scripts/MathUtils.cs:**
|
||||
```csharp
|
||||
using Godot;
|
||||
|
||||
namespace EinSoftworks.Utilities
|
||||
{
|
||||
public static class MathUtils
|
||||
{
|
||||
public static float Clamp01(float value) => Mathf.Clamp(value, 0f, 1f);
|
||||
|
||||
public static bool Approximately(float a, float b, float threshold = 0.001f)
|
||||
=> Mathf.Abs(a - b) < threshold;
|
||||
|
||||
public static float DegreesToRadians(float degrees) => degrees * Mathf.Pi / 180f;
|
||||
|
||||
public static float RadiansToDegrees(float radians) => radians * 180f / Mathf.Pi;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Create .gitignore
|
||||
|
||||
```gitignore
|
||||
.godot/
|
||||
.import/
|
||||
.mono/
|
||||
bin/
|
||||
obj/
|
||||
*.tmp
|
||||
export_presets.cfg
|
||||
```
|
||||
|
||||
### 5. Commit and Push
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Initial utilities library"
|
||||
git remote add origin https://git.ein-softworks.com/library/utilities.git
|
||||
git branch -M main
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
## Create a Game Project
|
||||
|
||||
### 1. Initialize Project
|
||||
|
||||
```bash
|
||||
cd ~/GameDev/projects
|
||||
git init test-game
|
||||
cd test-game
|
||||
mkdir -p Scripts Scenes Libraries
|
||||
```
|
||||
|
||||
### 2. Configure Project
|
||||
|
||||
**project.godot:**
|
||||
```ini
|
||||
[application]
|
||||
config/name="Test Game"
|
||||
config/features=PackedStringArray("4.3", "C#", "Forward Plus")
|
||||
run/main_scene="res://Scenes/Main.tscn"
|
||||
|
||||
[dotnet]
|
||||
project/assembly_name="TestGame"
|
||||
```
|
||||
|
||||
**TestGame.csproj:**
|
||||
```xml
|
||||
<Project Sdk="Godot.NET.Sdk/4.3.0">
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net6.0</TargetFramework>
|
||||
<EnableDynamicLoading>true</EnableDynamicLoading>
|
||||
<RootNamespace>TestGame</RootNamespace>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="Libraries/utilities/Utilities.csproj" />
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
### 3. Add Library as Submodule
|
||||
|
||||
```bash
|
||||
git submodule add https://git.ein-softworks.com/library/utilities.git Libraries/utilities
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
### 4. Use Library in Code
|
||||
|
||||
**Scripts/Main.cs:**
|
||||
```csharp
|
||||
using Godot;
|
||||
using EinSoftworks.Utilities;
|
||||
|
||||
namespace TestGame
|
||||
{
|
||||
public partial class Main : Node2D
|
||||
{
|
||||
public override void _Ready()
|
||||
{
|
||||
float radians = MathUtils.DegreesToRadians(90f);
|
||||
GD.Print($"90° = {radians} rad");
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Create Scene and Commit
|
||||
|
||||
Create `Scenes/Main.tscn` in Godot, then:
|
||||
|
||||
```bash
|
||||
cp ../utilities/.gitignore .
|
||||
git add .
|
||||
git commit -m "Initial test game with utilities library"
|
||||
git remote add origin https://git.ein-softworks.com/project/test-game.git
|
||||
git branch -M main
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
## Common Operations
|
||||
|
||||
### Update Library to Latest
|
||||
|
||||
```bash
|
||||
cd ~/GameDev/projects/test-game
|
||||
git submodule update --remote Libraries/utilities
|
||||
git add .
|
||||
git commit -m "Update utilities library"
|
||||
git push
|
||||
```
|
||||
|
||||
In Godot: **Project → Reload Current Project**, then rebuild.
|
||||
|
||||
### Update to Specific Version
|
||||
|
||||
```bash
|
||||
cd ~/GameDev/projects/test-game/Libraries/utilities
|
||||
git checkout v1.2.0
|
||||
cd ../..
|
||||
git add Libraries/utilities
|
||||
git commit -m "Update utilities to v1.2.0"
|
||||
git push
|
||||
```
|
||||
|
||||
### Add Another Library
|
||||
|
||||
```bash
|
||||
cd ~/GameDev/projects/test-game
|
||||
git submodule add https://git.ein-softworks.com/library/audio-manager.git Libraries/audio-manager
|
||||
```
|
||||
|
||||
Update **TestGame.csproj**:
|
||||
```xml
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="Libraries/utilities/Utilities.csproj" />
|
||||
<ProjectReference Include="Libraries/audio-manager/AudioManager.csproj" />
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Add audio-manager library"
|
||||
git push
|
||||
```
|
||||
|
||||
### Create New Project with Existing Libraries
|
||||
|
||||
```bash
|
||||
cd ~/GameDev/projects
|
||||
git init puzzle-game
|
||||
cd puzzle-game
|
||||
mkdir -p Scripts Scenes Libraries
|
||||
|
||||
# Add libraries
|
||||
git submodule add https://git.ein-softworks.com/library/utilities.git Libraries/utilities
|
||||
git submodule add https://git.ein-softworks.com/library/audio-manager.git Libraries/audio-manager
|
||||
git submodule update --init --recursive
|
||||
|
||||
# Create project.godot and .csproj with references
|
||||
# (see example structure above)
|
||||
|
||||
git add .
|
||||
git commit -m "Initial puzzle game setup"
|
||||
git remote add origin https://git.ein-softworks.com/project/puzzle-game.git
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
### Clone Project on New Machine
|
||||
|
||||
```bash
|
||||
git clone --recursive https://git.ein-softworks.com/project/test-game.git
|
||||
|
||||
# Or if already cloned
|
||||
cd test-game
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
## Library Dependencies
|
||||
|
||||
If one library depends on another, reference it in the .csproj:
|
||||
|
||||
**Libraries/ui-framework/UIFramework.csproj:**
|
||||
```xml
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="../utilities/Utilities.csproj" />
|
||||
</ItemGroup>
|
||||
```
|
||||
|
||||
## Version Control
|
||||
|
||||
### Create Library Release
|
||||
|
||||
```bash
|
||||
cd ~/GameDev/libraries/utilities
|
||||
git tag -a v1.0.0 -m "Release v1.0.0 - Initial stable release"
|
||||
git push origin v1.0.0
|
||||
```
|
||||
|
||||
### Development Workflow
|
||||
|
||||
```bash
|
||||
# Library development
|
||||
cd ~/GameDev/libraries/utilities
|
||||
git checkout -b feature/new-utils
|
||||
# Make changes
|
||||
git add .
|
||||
git commit -m "Add new utility functions"
|
||||
git push origin feature/new-utils
|
||||
# Merge in Gitea, then pull main
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# Update in project
|
||||
cd ~/GameDev/projects/test-game
|
||||
git submodule update --remote Libraries/utilities
|
||||
git add .
|
||||
git commit -m "Update utilities to latest"
|
||||
git push
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
**Library Design:**
|
||||
- Keep libraries focused and single-purpose
|
||||
- Use namespace pattern: `CompanyName.LibraryName`
|
||||
- Document public APIs with XML comments
|
||||
- Use semantic versioning (major.minor.patch)
|
||||
|
||||
**Project Organization:**
|
||||
- Use kebab-case for repos, PascalCase for namespaces
|
||||
- Only include needed libraries
|
||||
- Test after library updates
|
||||
|
||||
**Git Workflow:**
|
||||
- Use feature branches for development
|
||||
- Write clear commit messages
|
||||
- Push changes regularly
|
||||
- Tag important releases
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Submodule empty:**
|
||||
```bash
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
**Build errors:**
|
||||
- Godot → **Project → Reload Current Project**
|
||||
- **Project → Tools → C# → Create C# solution**
|
||||
- Rebuild
|
||||
|
||||
**Missing references:**
|
||||
Check `.csproj` has all `<ProjectReference>` entries.
|
||||
|
||||
**Submodule update conflicts:**
|
||||
```bash
|
||||
cd Libraries/utilities
|
||||
git stash
|
||||
git pull origin main
|
||||
git stash pop
|
||||
```
|
||||
|
||||
**IntelliSense not working:**
|
||||
- Reload Godot project
|
||||
- Rebuild solution
|
||||
- Restart VS Code with project folder open
|
||||
215
environment/VSCODE_INTEGRATION.md
Normal file
215
environment/VSCODE_INTEGRATION.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# VS Code Setup for Godot Development
|
||||
|
||||
## Why VS Code?
|
||||
|
||||
Better IntelliSense, Git integration, extensions, debugging, and multi-project support compared to Godot's built-in editor.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Godot v4.5.1+ (C# support)
|
||||
- .NET 8.0+
|
||||
- Visual Studio Code
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Install Extensions
|
||||
|
||||
**Required:**
|
||||
```bash
|
||||
code --install-extension ms-dotnettools.csdevkit
|
||||
code --install-extension ms-dotnettools.csharp
|
||||
code --install-extension geequlim.godot-tools
|
||||
```
|
||||
|
||||
**Recommended:**
|
||||
```bash
|
||||
code --install-extension visualstudioexptteam.vscodeintellicode
|
||||
code --install-extension eamodio.gitlens
|
||||
code --install-extension streetsidesoftware.code-spell-checker
|
||||
```
|
||||
|
||||
### 2. Configure Godot
|
||||
|
||||
**Editor Settings:**
|
||||
1. **Editor → Editor Settings → Network → Language Server**
|
||||
- Enable **Use Language Server**
|
||||
|
||||
2. **Text Editor → External**
|
||||
- Check **Use External Editor**
|
||||
- **Exec Path:**
|
||||
- macOS: `/Applications/Visual Studio Code.app/Contents/Resources/app/bin/code`
|
||||
- Windows: `C:\Users\[Username]\AppData\Local\Programs\Microsoft VS Code\Code.exe`
|
||||
- Linux: `/usr/bin/code` or just `code`
|
||||
|
||||
### 3. Fix Project Context (Choose One)
|
||||
|
||||
**Option A - Simple Flags (Easiest):**
|
||||
```
|
||||
{project} --goto {file}:{line}:{col}
|
||||
```
|
||||
|
||||
**Option B - Wrapper Script (Best):**
|
||||
|
||||
**macOS/Linux** (`~/GameDev/vscode-godot.sh`):
|
||||
```bash
|
||||
#!/bin/bash
|
||||
FILE_PATH="$1"
|
||||
LINE_NUMBER="$2"
|
||||
COLUMN_NUMBER="$3"
|
||||
|
||||
PROJECT_DIR=$(dirname "$FILE_PATH")
|
||||
while [[ "$PROJECT_DIR" != "/" && ! -f "$PROJECT_DIR/project.godot" ]]; do
|
||||
PROJECT_DIR=$(dirname "$PROJECT_DIR")
|
||||
done
|
||||
|
||||
if [[ -f "$PROJECT_DIR/project.godot" ]]; then
|
||||
code "$PROJECT_DIR" --goto "$FILE_PATH:$LINE_NUMBER:$COLUMN_NUMBER"
|
||||
else
|
||||
code "$(dirname "$FILE_PATH")" --goto "$FILE_PATH:$LINE_NUMBER:$COLUMN_NUMBER"
|
||||
fi
|
||||
```
|
||||
|
||||
**Windows** (`~/GameDev/vscode-godot.ps1`):
|
||||
```powershell
|
||||
param($FilePath, $LineNumber = "1", $ColumnNumber = "1")
|
||||
|
||||
$ProjectDir = Split-Path $FilePath -Parent
|
||||
while (($ProjectDir -ne [System.IO.Path]::GetPathRoot($ProjectDir)) -and
|
||||
(-not (Test-Path (Join-Path $ProjectDir "project.godot")))) {
|
||||
$ProjectDir = Split-Path $ProjectDir -Parent
|
||||
}
|
||||
|
||||
if (Test-Path (Join-Path $ProjectDir "project.godot")) {
|
||||
& code $ProjectDir --goto "$FilePath`:$LineNumber`:$ColumnNumber"
|
||||
} else {
|
||||
& code (Split-Path $FilePath -Parent) --goto "$FilePath`:$LineNumber`:$ColumnNumber"
|
||||
}
|
||||
```
|
||||
|
||||
Make script executable: `chmod +x ~/GameDev/vscode-godot.sh`
|
||||
|
||||
Set **Exec Flags**: `{file} {line} {col}`
|
||||
|
||||
## Project Configuration
|
||||
|
||||
### .vscode/settings.json
|
||||
```json
|
||||
{
|
||||
"dotnet.defaultSolution": "YourGame.sln",
|
||||
"omnisharp.useModernNet": true,
|
||||
"godot_tools.editor_path": "/path/to/Godot",
|
||||
|
||||
"files.exclude": {
|
||||
"**/.godot": true,
|
||||
"**/bin": true,
|
||||
"**/obj": true
|
||||
},
|
||||
|
||||
"window.openFilesInNewWindow": "off",
|
||||
"editor.formatOnSave": true,
|
||||
"git.detectSubmodules": true
|
||||
}
|
||||
```
|
||||
|
||||
### .vscode/launch.json
|
||||
```json
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"configurations": [
|
||||
{
|
||||
"name": "Play in Editor",
|
||||
"type": "godot",
|
||||
"request": "launch",
|
||||
"project": "${workspaceFolder}",
|
||||
"port": 6007
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### .vscode/tasks.json
|
||||
```json
|
||||
{
|
||||
"version": "2.0.0",
|
||||
"tasks": [
|
||||
{
|
||||
"label": "build",
|
||||
"command": "dotnet",
|
||||
"type": "process",
|
||||
"args": ["build"],
|
||||
"problemMatcher": "$msCompile"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### .editorconfig (Optional)
|
||||
```ini
|
||||
root = true
|
||||
|
||||
[*]
|
||||
charset = utf-8
|
||||
insert_final_newline = true
|
||||
|
||||
[*.cs]
|
||||
indent_style = space
|
||||
indent_size = 4
|
||||
```
|
||||
|
||||
## Multi-Project Workspace
|
||||
|
||||
Create `your-workspace.code-workspace`:
|
||||
```json
|
||||
{
|
||||
"folders": [
|
||||
{"path": "projects/main-game"},
|
||||
{"path": "libraries/utilities"},
|
||||
{"path": "libraries/extensions"}
|
||||
],
|
||||
"settings": {
|
||||
"omnisharp.useModernNet": true,
|
||||
"files.exclude": {
|
||||
"**/.godot": true,
|
||||
"**/bin": true,
|
||||
"**/obj": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Shortcuts
|
||||
|
||||
- **Go to Definition**: `F12`
|
||||
- **Find References**: `Shift + F12`
|
||||
- **Go to Symbol**: `Cmd/Ctrl + Shift + O`
|
||||
- **Command Palette**: `Cmd/Ctrl + Shift + P`
|
||||
- **Search Files**: `Cmd/Ctrl + P`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**IntelliSense not working:**
|
||||
- Reload window: `Cmd/Ctrl + Shift + P` → "Developer: Reload Window"
|
||||
- Rebuild: `dotnet build`
|
||||
|
||||
**Project opens as single file:**
|
||||
- Use wrapper script or set Exec Flags to `{project} --goto {file}:{line}:{col}`
|
||||
|
||||
**Submodules not recognized:**
|
||||
```bash
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
Add to settings: `"git.detectSubmodules": true`
|
||||
|
||||
**Performance issues:**
|
||||
- Exclude build folders in settings
|
||||
- Disable unused extensions
|
||||
- Run: `code --max-memory=8192`
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Keep consistent project structure
|
||||
- Commit often with clear messages
|
||||
- Use feature branches
|
||||
- Exclude build folders (.godot, bin, obj)
|
||||
- Enable format on save
|
||||
- Document public APIs
|
||||
Reference in New Issue
Block a user