Update docs/LIBRARY_MANAGEMENT.md
This commit is contained in:
361
docs/LIBRARY_MANAGEMENT.md
Normal file
361
docs/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
|
||||
@@ -1,806 +0,0 @@
|
||||
# Godot C# Library Management System
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes a comprehensive system for managing reusable C# libraries across multiple Godot game projects using Git submodules. This approach enables clean separation of concerns, version control for individual libraries, and easy code reuse across multiple game projects.
|
||||
|
||||
## System Architecture
|
||||
|
||||
### Core Principles
|
||||
|
||||
1. **Separation of Concerns**: Libraries and game projects exist in separate Git repositories
|
||||
2. **Modular Design**: Each library serves a specific purpose and can be developed independently
|
||||
3. **Version Control**: Libraries can be versioned and updated independently of game projects
|
||||
4. **Code Reuse**: Multiple projects can share the same libraries without code duplication
|
||||
5. **Clean Dependencies**: C# project references ensure proper compilation and IntelliSense support
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
~/GameDev/
|
||||
├── Godot/ # Godot engine installation
|
||||
├── libraries/ # Local development copies of libraries
|
||||
│ ├── utilities/ # Example: utilities library repository
|
||||
│ ├── audio-manager/ # Example: audio management library
|
||||
│ └── ui-framework/ # Example: UI framework library
|
||||
└── projects/ # Game project repositories
|
||||
├── test-game/ # Example: test game project
|
||||
│ └── Libraries/ # Git submodules directory
|
||||
│ ├── utilities/ # Submodule → library/utilities
|
||||
│ └── audio-manager/# Submodule → library/audio-manager
|
||||
└── puzzle-game/ # Example: another game project
|
||||
└── Libraries/ # Git submodules directory
|
||||
└── utilities/ # Submodule → library/utilities
|
||||
```
|
||||
|
||||
### Git Repository Organization
|
||||
|
||||
**Gitea Organizations:**
|
||||
- `library/` - Contains all reusable library repositories
|
||||
- `project/` - Contains all game project repositories
|
||||
|
||||
**Repository Examples:**
|
||||
- `https://git.ein-softworks.com/library/utilities.git`
|
||||
- `https://git.ein-softworks.com/library/audio-manager.git`
|
||||
- `https://git.ein-softworks.com/project/test-game.git`
|
||||
- `https://git.ein-softworks.com/project/puzzle-game.git`
|
||||
|
||||
## How Git Submodules Work
|
||||
|
||||
Git submodules allow you to include one Git repository inside another as a subdirectory. In our case:
|
||||
|
||||
1. **Library repositories** contain reusable C# code and Godot scenes
|
||||
2. **Game project repositories** include libraries as submodules in their `Libraries/` directory
|
||||
3. **Submodules point to specific commits** in the library repositories, ensuring reproducible builds
|
||||
4. **Updates are explicit** - you control when to pull in library changes
|
||||
|
||||
### Benefits of This Approach
|
||||
|
||||
- **Independent Development**: Work on libraries without affecting game projects
|
||||
- **Version Stability**: Games use specific library versions until explicitly updated
|
||||
- **Selective Updates**: Choose which libraries to update in each project
|
||||
- **Clean History**: Each repository maintains its own commit history
|
||||
- **Collaborative Friendly**: Multiple developers can work on different libraries simultaneously
|
||||
|
||||
## Initial Setup Process
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- macOS with Godot v4.5.1 stable installed at `~/GameDev/Godot/`
|
||||
- .NET 8.0.121 installed
|
||||
- Git configured with access to your Gitea instance
|
||||
- Gitea instance with `library` and `project` organizations created
|
||||
|
||||
### Step 1: Create Directory Structure
|
||||
|
||||
```bash
|
||||
cd ~/GameDev
|
||||
mkdir -p libraries projects
|
||||
```
|
||||
|
||||
### Step 2: Create Your First Library
|
||||
|
||||
#### Initialize the Library Repository
|
||||
|
||||
```bash
|
||||
cd ~/GameDev/libraries
|
||||
git init utilities
|
||||
cd utilities
|
||||
mkdir -p Scripts
|
||||
```
|
||||
|
||||
#### Create Library Project Configuration
|
||||
|
||||
Create `project.godot`:
|
||||
```ini
|
||||
; Engine configuration file.
|
||||
|
||||
[application]
|
||||
|
||||
config/name="Utilities Library"
|
||||
config/features=PackedStringArray("4.3", "C#", "Forward Plus")
|
||||
|
||||
[dotnet]
|
||||
|
||||
project/assembly_name="EinSoftworks.Utilities"
|
||||
```
|
||||
|
||||
Create `Utilities.csproj`:
|
||||
```xml
|
||||
<Project Sdk="Godot.NET.Sdk/4.3.0">
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net6.0</TargetFramework>
|
||||
<TargetFramework Condition=" '$(GodotTargetPlatform)' == 'android' ">net7.0</TargetFramework>
|
||||
<TargetFramework Condition=" '$(GodotTargetPlatform)' == 'ios' ">net8.0</TargetFramework>
|
||||
<EnableDynamicLoading>true</EnableDynamicLoading>
|
||||
<RootNamespace>EinSoftworks.Utilities</RootNamespace>
|
||||
<AssemblyName>EinSoftworks.Utilities</AssemblyName>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
#### Create Example Library Code
|
||||
|
||||
Create `Scripts/MathUtils.cs`:
|
||||
```csharp
|
||||
using Godot;
|
||||
|
||||
namespace EinSoftworks.Utilities
|
||||
{
|
||||
public static class MathUtils
|
||||
{
|
||||
/// <summary>
|
||||
/// Clamps a value between 0 and 1.
|
||||
/// </summary>
|
||||
public static float Clamp01(float value)
|
||||
{
|
||||
return Mathf.Clamp(value, 0f, 1f);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Checks if a number is approximately equal to another number.
|
||||
/// </summary>
|
||||
public static bool Approximately(float a, float b, float threshold = 0.001f)
|
||||
{
|
||||
return Mathf.Abs(a - b) < threshold;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Converts degrees to radians.
|
||||
/// </summary>
|
||||
public static float DegreesToRadians(float degrees)
|
||||
{
|
||||
return degrees * Mathf.Pi / 180f;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Converts radians to degrees.
|
||||
/// </summary>
|
||||
public static float RadiansToDegrees(float radians)
|
||||
{
|
||||
return radians * 180f / Mathf.Pi;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Create .gitignore
|
||||
|
||||
```gitignore
|
||||
# Godot 4+ specific ignores
|
||||
.godot/
|
||||
|
||||
# Godot-specific ignores
|
||||
.import/
|
||||
export.cfg
|
||||
export_presets.cfg
|
||||
|
||||
# Imported translations (automatically generated from CSV files)
|
||||
*.translation
|
||||
|
||||
# Mono-specific ignores
|
||||
.mono/
|
||||
data_*/
|
||||
mono_crash.*.json
|
||||
|
||||
# .NET specific ignores
|
||||
bin/
|
||||
obj/
|
||||
*.tmp
|
||||
```
|
||||
|
||||
#### Commit and Push Library
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Initial utilities library setup with MathUtils"
|
||||
git remote add origin https://git.ein-softworks.com/library/utilities.git
|
||||
git branch -M main
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
### Step 3: Create Your First Game Project
|
||||
|
||||
#### Initialize the Game Repository
|
||||
|
||||
```bash
|
||||
cd ~/GameDev/projects
|
||||
git init test-game
|
||||
cd test-game
|
||||
mkdir -p Scripts Scenes Libraries
|
||||
```
|
||||
|
||||
#### Create Game Project Configuration
|
||||
|
||||
Create `project.godot`:
|
||||
```ini
|
||||
; Engine configuration file.
|
||||
|
||||
[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"
|
||||
```
|
||||
|
||||
Create `TestGame.csproj`:
|
||||
```xml
|
||||
<Project Sdk="Godot.NET.Sdk/4.3.0">
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net6.0</TargetFramework>
|
||||
<TargetFramework Condition=" '$(GodotTargetPlatform)' == 'android' ">net7.0</TargetFramework>
|
||||
<TargetFramework Condition=" '$(GodotTargetPlatform)' == 'ios' ">net8.0</TargetFramework>
|
||||
<EnableDynamicLoading>true</EnableDynamicLoading>
|
||||
<RootNamespace>TestGame</RootNamespace>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="Libraries/utilities/Utilities.csproj" />
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
#### Add Library as Submodule
|
||||
|
||||
```bash
|
||||
git submodule add https://git.ein-softworks.com/library/utilities.git Libraries/utilities
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
#### Create Game Code
|
||||
|
||||
Create `Scripts/Main.cs`:
|
||||
```csharp
|
||||
using Godot;
|
||||
using EinSoftworks.Utilities;
|
||||
|
||||
namespace TestGame
|
||||
{
|
||||
public partial class Main : Node2D
|
||||
{
|
||||
public override void _Ready()
|
||||
{
|
||||
GD.Print("Test Game Started!");
|
||||
|
||||
// Test the utilities library
|
||||
TestMathUtils();
|
||||
}
|
||||
|
||||
private void TestMathUtils()
|
||||
{
|
||||
// Test degree/radian conversion
|
||||
float testAngle = 90f;
|
||||
float radians = MathUtils.DegreesToRadians(testAngle);
|
||||
float backToDegrees = MathUtils.RadiansToDegrees(radians);
|
||||
GD.Print($"90° → {radians} rad → {backToDegrees}°");
|
||||
|
||||
// Test clamping
|
||||
float clampedValue = MathUtils.Clamp01(1.5f);
|
||||
GD.Print($"Clamped 1.5 to 0-1 range: {clampedValue}");
|
||||
|
||||
// Test approximation
|
||||
bool isApprox = MathUtils.Approximately(0.1f, 0.100001f);
|
||||
GD.Print($"0.1 ≈ 0.100001: {isApprox}");
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Create `Scenes/Main.tscn`:
|
||||
```
|
||||
[gd_scene load_steps=2 format=3 uid="uid://b8y1qxqxqxqxq"]
|
||||
|
||||
[ext_resource type="Script" path="res://Scripts/Main.cs" id="1"]
|
||||
|
||||
[node name="Main" type="Node2D"]
|
||||
script = ExtResource("1")
|
||||
|
||||
[node name="Label" type="Label" parent="."]
|
||||
offset_right = 400.0
|
||||
offset_bottom = 100.0
|
||||
text = "Test Game - Check console for utilities library output"
|
||||
horizontal_alignment = 1
|
||||
vertical_alignment = 1
|
||||
```
|
||||
|
||||
#### Create .gitignore
|
||||
|
||||
```gitignore
|
||||
# Godot 4+ specific ignores
|
||||
.godot/
|
||||
|
||||
# Godot-specific ignores
|
||||
.import/
|
||||
export.cfg
|
||||
export_presets.cfg
|
||||
|
||||
# Imported translations (automatically generated from CSV files)
|
||||
*.translation
|
||||
|
||||
# Mono-specific ignores
|
||||
.mono/
|
||||
data_*/
|
||||
mono_crash.*.json
|
||||
|
||||
# .NET specific ignores
|
||||
bin/
|
||||
obj/
|
||||
*.tmp
|
||||
```
|
||||
|
||||
#### Commit and Push Game Project
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Initial test game setup with utilities library submodule"
|
||||
git remote add origin https://git.ein-softworks.com/project/test-game.git
|
||||
git branch -M main
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
### Step 4: Open and Build in Godot
|
||||
|
||||
1. Launch Godot: `~/GameDev/Godot/Godot.app/Contents/MacOS/Godot`
|
||||
2. In Project Manager, click **"Import"**
|
||||
3. Navigate to `~/GameDev/projects/test-game/` and select `project.godot`
|
||||
4. Click **"Import & Edit"**
|
||||
5. In the Godot editor, go to **Project → Tools → C# → Create C# solution**
|
||||
6. Click the **"Build"** button in the toolbar (or **Project → Tools → C# → Build Solution**)
|
||||
7. Run the game with the **Play** button
|
||||
|
||||
Expected console output:
|
||||
```
|
||||
Test Game Started!
|
||||
90° → 1.5708 rad → 90°
|
||||
Clamped 1.5 to 0-1 range: 1
|
||||
0.1 ≈ 0.100001: True
|
||||
```
|
||||
|
||||
## Usage Workflows
|
||||
|
||||
### Working on Libraries
|
||||
|
||||
#### Developing New Features
|
||||
|
||||
When you want to add functionality to an existing library:
|
||||
|
||||
```bash
|
||||
# Navigate to library
|
||||
cd ~/GameDev/libraries/utilities
|
||||
|
||||
# Create a new branch for your feature
|
||||
git checkout -b feature/string-utilities
|
||||
|
||||
# Add your new code (example)
|
||||
cat >> Scripts/StringUtils.cs << 'EOF'
|
||||
using Godot;
|
||||
|
||||
namespace EinSoftworks.Utilities
|
||||
{
|
||||
public static class StringUtils
|
||||
{
|
||||
public static string ToPascalCase(string input)
|
||||
{
|
||||
if (string.IsNullOrEmpty(input)) return input;
|
||||
return char.ToUpper(input[0]) + input.Substring(1).ToLower();
|
||||
}
|
||||
|
||||
public static bool IsValidEmail(string email)
|
||||
{
|
||||
return email.Contains("@") && email.Contains(".");
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
|
||||
# Test your changes in Godot
|
||||
# Open ~/GameDev/libraries/utilities in Godot
|
||||
# Build and test the library
|
||||
|
||||
# Commit your changes
|
||||
git add .
|
||||
git commit -m "Add StringUtils with PascalCase and email validation"
|
||||
|
||||
# Push the feature branch
|
||||
git push origin feature/string-utilities
|
||||
|
||||
# Create a pull request in Gitea
|
||||
# After review and merge, switch back to main
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# Clean up feature branch
|
||||
git branch -d feature/string-utilities
|
||||
```
|
||||
|
||||
#### Creating a New Library
|
||||
|
||||
```bash
|
||||
# Create new library repository
|
||||
cd ~/GameDev/libraries
|
||||
git init audio-manager
|
||||
cd audio-manager
|
||||
|
||||
# Set up library structure
|
||||
mkdir -p Scripts Resources
|
||||
cat > project.godot << 'EOF'
|
||||
; Engine configuration file.
|
||||
|
||||
[application]
|
||||
|
||||
config/name="Audio Manager Library"
|
||||
config/features=PackedStringArray("4.3", "C#", "Forward Plus")
|
||||
|
||||
[dotnet]
|
||||
|
||||
project/assembly_name="EinSoftworks.AudioManager"
|
||||
EOF
|
||||
|
||||
cat > AudioManager.csproj << 'EOF'
|
||||
<Project Sdk="Godot.NET.Sdk/4.3.0">
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net6.0</TargetFramework>
|
||||
<TargetFramework Condition=" '$(GodotTargetPlatform)' == 'android' ">net7.0</TargetFramework>
|
||||
<TargetFramework Condition=" '$(GodotTargetPlatform)' == 'ios' ">net8.0</TargetFramework>
|
||||
<EnableDynamicLoading>true</EnableDynamicLoading>
|
||||
<RootNamespace>EinSoftworks.AudioManager</RootNamespace>
|
||||
<AssemblyName>EinSoftworks.AudioManager</AssemblyName>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
EOF
|
||||
|
||||
# Create basic audio manager
|
||||
cat > Scripts/AudioManager.cs << 'EOF'
|
||||
using Godot;
|
||||
|
||||
namespace EinSoftworks.AudioManager
|
||||
{
|
||||
public partial class AudioManager : Node
|
||||
{
|
||||
private AudioStreamPlayer _musicPlayer;
|
||||
private AudioStreamPlayer _sfxPlayer;
|
||||
|
||||
public override void _Ready()
|
||||
{
|
||||
_musicPlayer = new AudioStreamPlayer();
|
||||
_sfxPlayer = new AudioStreamPlayer();
|
||||
|
||||
AddChild(_musicPlayer);
|
||||
AddChild(_sfxPlayer);
|
||||
}
|
||||
|
||||
public void PlayMusic(AudioStream music, float volume = 1.0f)
|
||||
{
|
||||
_musicPlayer.Stream = music;
|
||||
_musicPlayer.VolumeDb = Mathf.LinearToDb(volume);
|
||||
_musicPlayer.Play();
|
||||
}
|
||||
|
||||
public void PlaySFX(AudioStream sfx, float volume = 1.0f)
|
||||
{
|
||||
_sfxPlayer.Stream = sfx;
|
||||
_sfxPlayer.VolumeDb = Mathf.LinearToDb(volume);
|
||||
_sfxPlayer.Play();
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
|
||||
# Copy standard .gitignore
|
||||
cp ../utilities/.gitignore .
|
||||
|
||||
# Commit and push
|
||||
git add .
|
||||
git commit -m "Initial audio manager library"
|
||||
git remote add origin https://git.ein-softworks.com/library/audio-manager.git
|
||||
git branch -M main
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
### Working with Game Projects
|
||||
|
||||
#### Adding Libraries to Existing Projects
|
||||
|
||||
To add a new library to an existing game project:
|
||||
|
||||
```bash
|
||||
# Navigate to your game project
|
||||
cd ~/GameDev/projects/test-game
|
||||
|
||||
# Add the new library as a submodule
|
||||
git submodule add https://git.ein-softworks.com/library/audio-manager.git Libraries/audio-manager
|
||||
|
||||
# Update the .csproj file to reference the new library
|
||||
# Edit TestGame.csproj and add to ItemGroup:
|
||||
# <ProjectReference Include="Libraries/audio-manager/AudioManager.csproj" />
|
||||
|
||||
# Example of the updated .csproj:
|
||||
cat > TestGame.csproj << 'EOF'
|
||||
<Project Sdk="Godot.NET.Sdk/4.3.0">
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net6.0</TargetFramework>
|
||||
<TargetFramework Condition=" '$(GodotTargetPlatform)' == 'android' ">net7.0</TargetFramework>
|
||||
<TargetFramework Condition=" '$(GodotTargetPlatform)' == 'ios' ">net8.0</TargetFramework>
|
||||
<EnableDynamicLoading>true</EnableDynamicLoading>
|
||||
<RootNamespace>TestGame</RootNamespace>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="Libraries/utilities/Utilities.csproj" />
|
||||
<ProjectReference Include="Libraries/audio-manager/AudioManager.csproj" />
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
EOF
|
||||
|
||||
# Commit the changes
|
||||
git add .
|
||||
git commit -m "Add audio-manager library dependency"
|
||||
git push origin main
|
||||
|
||||
# In Godot: Project → Reload Current Project
|
||||
# Then build the solution
|
||||
```
|
||||
|
||||
#### Updating Libraries in Projects
|
||||
|
||||
To update a library to the latest version:
|
||||
|
||||
```bash
|
||||
# Navigate to your game project
|
||||
cd ~/GameDev/projects/test-game
|
||||
|
||||
# Update specific library to latest
|
||||
git submodule update --remote Libraries/utilities
|
||||
|
||||
# Or update all submodules
|
||||
git submodule update --remote
|
||||
|
||||
# Commit the library updates
|
||||
git add .
|
||||
git commit -m "Update utilities library to latest version"
|
||||
git push origin main
|
||||
|
||||
# In Godot: Project → Reload Current Project
|
||||
# Then rebuild the solution
|
||||
```
|
||||
|
||||
To update to a specific version/commit:
|
||||
|
||||
```bash
|
||||
# Navigate to the submodule
|
||||
cd ~/GameDev/projects/test-game/Libraries/utilities
|
||||
|
||||
# Check available tags/versions
|
||||
git tag -l
|
||||
|
||||
# Checkout specific version
|
||||
git checkout v1.2.0
|
||||
|
||||
# Go back to project root
|
||||
cd ~/GameDev/projects/test-game
|
||||
|
||||
# Commit the specific version
|
||||
git add Libraries/utilities
|
||||
git commit -m "Update utilities library to v1.2.0"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
#### Creating New Game Projects
|
||||
|
||||
To create a new game project with existing libraries:
|
||||
|
||||
```bash
|
||||
# Create new project
|
||||
cd ~/GameDev/projects
|
||||
git init puzzle-game
|
||||
cd puzzle-game
|
||||
|
||||
# Set up basic structure
|
||||
mkdir -p Scripts Scenes Libraries
|
||||
|
||||
# Create project.godot
|
||||
cat > project.godot << 'EOF'
|
||||
; Engine configuration file.
|
||||
|
||||
[application]
|
||||
|
||||
config/name="Puzzle Game"
|
||||
config/features=PackedStringArray("4.3", "C#", "Forward Plus")
|
||||
run/main_scene="res://Scenes/Main.tscn"
|
||||
|
||||
[dotnet]
|
||||
|
||||
project/assembly_name="PuzzleGame"
|
||||
EOF
|
||||
|
||||
# Add required 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
|
||||
|
||||
# Create .csproj with all dependencies
|
||||
cat > PuzzleGame.csproj << 'EOF'
|
||||
<Project Sdk="Godot.NET.Sdk/4.3.0">
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net6.0</TargetFramework>
|
||||
<TargetFramework Condition=" '$(GodotTargetPlatform)' == 'android' ">net7.0</TargetFramework>
|
||||
<TargetFramework Condition=" '$(GodotTargetPlatform)' == 'ios' ">net8.0</TargetFramework>
|
||||
<EnableDynamicLoading>true</EnableDynamicLoading>
|
||||
<RootNamespace>PuzzleGame</RootNamespace>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="Libraries/utilities/Utilities.csproj" />
|
||||
<ProjectReference Include="Libraries/audio-manager/AudioManager.csproj" />
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
EOF
|
||||
|
||||
# Copy .gitignore from another project
|
||||
cp ../test-game/.gitignore .
|
||||
|
||||
# Initialize submodules
|
||||
git submodule update --init --recursive
|
||||
|
||||
# Create basic game code
|
||||
cat > Scripts/Main.cs << 'EOF'
|
||||
using Godot;
|
||||
using EinSoftworks.Utilities;
|
||||
using EinSoftworks.AudioManager;
|
||||
|
||||
namespace PuzzleGame
|
||||
{
|
||||
public partial class Main : Node2D
|
||||
{
|
||||
private AudioManager _audioManager;
|
||||
|
||||
public override void _Ready()
|
||||
{
|
||||
GD.Print("Puzzle Game Started!");
|
||||
|
||||
// Set up audio manager
|
||||
_audioManager = new AudioManager();
|
||||
AddChild(_audioManager);
|
||||
|
||||
// Test utilities
|
||||
float angle = MathUtils.DegreesToRadians(45f);
|
||||
GD.Print($"45 degrees = {angle} radians");
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF
|
||||
|
||||
# Commit and push
|
||||
git add .
|
||||
git commit -m "Initial puzzle game setup with utilities and audio-manager libraries"
|
||||
git remote add origin https://git.ein-softworks.com/project/puzzle-game.git
|
||||
git branch -M main
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
### Advanced Workflows
|
||||
|
||||
#### Working with Library Dependencies
|
||||
|
||||
If one library depends on another:
|
||||
|
||||
```csharp
|
||||
// In Libraries/ui-framework/UIFramework.csproj
|
||||
<Project Sdk="Godot.NET.Sdk/4.3.0">
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net6.0</TargetFramework>
|
||||
<EnableDynamicLoading>true</EnableDynamicLoading>
|
||||
<RootNamespace>EinSoftworks.UIFramework</RootNamespace>
|
||||
<AssemblyName>EinSoftworks.UIFramework</AssemblyName>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="../utilities/Utilities.csproj" />
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
```
|
||||
|
||||
#### Creating Library Releases
|
||||
|
||||
For important library milestones:
|
||||
|
||||
```bash
|
||||
# In your library repository
|
||||
cd ~/GameDev/libraries/utilities
|
||||
|
||||
# Create and push a tag
|
||||
git tag -a v1.0.0 -m "Release version 1.0.0 - Initial stable release"
|
||||
git push origin v1.0.0
|
||||
|
||||
# Create release notes in Gitea
|
||||
# Navigate to your Gitea repository → Releases → New Release
|
||||
```
|
||||
|
||||
#### Cloning Projects on New Machines
|
||||
|
||||
When setting up on a new development machine:
|
||||
|
||||
```bash
|
||||
# Clone project with submodules
|
||||
git clone --recursive https://git.ein-softworks.com/project/test-game.git
|
||||
|
||||
# Or if already cloned without --recursive
|
||||
cd test-game
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Library Design
|
||||
|
||||
1. **Keep libraries focused**: Each library should have a single, well-defined purpose
|
||||
2. **Use proper namespacing**: Follow the pattern `CompanyName.LibraryName`
|
||||
3. **Document your code**: Use XML documentation comments for public APIs
|
||||
4. **Version your releases**: Use semantic versioning (major.minor.patch)
|
||||
5. **Test thoroughly**: Create test projects for each library
|
||||
|
||||
### Project Organization
|
||||
|
||||
1. **Consistent naming**: Use kebab-case for repository names, PascalCase for namespaces
|
||||
2. **Clear dependencies**: Only include libraries you actually use
|
||||
3. **Regular updates**: Keep libraries updated, but test thoroughly after updates
|
||||
4. **Backup strategy**: Ensure all repositories are backed up on your Gitea instance
|
||||
|
||||
### Git Workflow
|
||||
|
||||
1. **Feature branches**: Use feature branches for library development
|
||||
2. **Descriptive commits**: Write clear commit messages
|
||||
3. **Regular pushes**: Push changes regularly to avoid data loss
|
||||
4. **Clean history**: Squash commits when merging features
|
||||
|
||||
### Development Environment
|
||||
|
||||
1. **Consistent paths**: Always use the `~/GameDev/` structure
|
||||
2. **IDE setup**: Configure your IDE to recognize the library references
|
||||
3. **Build automation**: Consider setting up CI/CD for library testing
|
||||
4. **Documentation**: Keep this document updated as your system evolves
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Submodule Not Found
|
||||
```bash
|
||||
# If Libraries/utilities is empty
|
||||
cd ~/GameDev/projects/test-game
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
#### Build Errors
|
||||
```bash
|
||||
# In Godot editor
|
||||
# Project → Reload Current Project
|
||||
# Project → Tools → C# → Create C# solution
|
||||
# Build
|
||||
```
|
||||
|
||||
#### Missing References
|
||||
Check that your `.csproj` file includes all required `<ProjectReference>` entries for your submodules.
|
||||
|
||||
#### Submodule Update Conflicts
|
||||
```bash
|
||||
# If you have uncommitted changes in a submodule
|
||||
cd Libraries/utilities
|
||||
git stash
|
||||
git pull origin main
|
||||
git stash pop
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
|
||||
1. Check Godot's C# documentation
|
||||
2. Review Git submodule documentation
|
||||
3. Examine this document for reference patterns
|
||||
4. Test changes in isolation before applying to important projects
|
||||
|
||||
---
|
||||
|
||||
*This documentation should be updated as your library system evolves and new patterns emerge.*
|
||||
Reference in New Issue
Block a user