Auto Warz — GitHub Setup Guide¶

Document Type: Technical Setup Version: 0.1 Last Updated: 2026-02-23 Vault destination: 04_Project Management Author: Solo Developer Related Documents: [01_Technical Architecture Document](<../02_Technical Documents/01_Technical Architecture Document.md>) · [01_Development Roadmap](<./01_Development Roadmap.md>)

Overview¶

This guide walks through the complete GitHub setup for Auto Warz — from creating the repository to making your first commit. Follow the steps in order.

What we're setting up: - GitHub repository (public or private — your choice) - Godot 4-specific .gitignore — keeps the repo clean and fast - Initial project folder structure - Branching strategy suited to solo hobby development - Conventional commit message format - First commit

Time required: ~30–45 minutes

Step 1 — Create the GitHub Repository¶

Go to github.com and sign in
Click the + icon (top right) → New repository
Fill in the details:

Field	Value
Repository name	`auto-warz`
Description	`Factory automation, space exploration, and RTS — built in Godot 4`
Visibility	Private (recommended while in development — switch to public when ready to share)
Initialize with README	✅ Yes
Add .gitignore	None — we'll create a better one manually
License	MIT (recommended for an indie game)

Click Create repository

Step 2 — Clone the Repository Locally¶

Open Git Bash or Windows Terminal and run:

cd C:/Dev    # or wherever you keep your projects
git clone https://github.com/YOUR_USERNAME/auto-warz.git
cd auto-warz

Step 3 — Create the Godot 4 Project Inside the Repository¶

Open Godot 4
Click New Project
Set the project path to your cloned repository folder: C:/Dev/auto-warz
Project name: Auto Warz
Renderer: Forward+ (as per Technical Architecture Document)
Click Create & Edit

Godot will create its project files inside your repository folder. Do not create a subfolder — the Godot project lives at the root of the repo.

Step 4 — Create the .gitignore¶

This is the most important step. A bad .gitignore for Godot causes two problems: - Committing the .godot/ folder (tens of thousands of auto-generated files — bloats the repo badly) - Missing important files that should be tracked

Create a file called .gitignore in the root of the repository with this content:

# ============================================================
# AUTO WARZ — GODOT 4 .gitignore
# ============================================================

# Godot auto-generated import cache — NEVER commit this
# It is large, machine-specific, and fully regenerated on open
.godot/

# Godot editor settings (machine-specific)
# These contain local paths that differ per developer
*.uid

# Export templates and build outputs
export_presets.cfg
exports/
builds/

# Godot mono/C# build artifacts (not used — GDScript only)
.mono/
data_*/
mono_crash.*.json

# ============================================================
# WINDOWS
# ============================================================
Thumbs.db
ehthumbs.db
Desktop.ini
$RECYCLE.BIN/
*.lnk

# ============================================================
# VS CODE
# ============================================================
.vscode/settings.json
.vscode/launch.json
.vscode/tasks.json
# Keep: .vscode/extensions.json (useful for team recommendations)

# ============================================================
# SENSITIVE / LOCAL CONFIG
# ============================================================
# Steam API key or any other secrets — NEVER commit these
*.env
.env.*
steam_appid.txt

# Local save files (player data — not source code)
user_saves/

# ============================================================
# AI TOOL OUTPUTS (temporary generation files)
# ============================================================
ai_outputs/
midjourney_temp/
meshy_temp/

# ============================================================
# MISC
# ============================================================
*.tmp
*.bak
*.swp
*~

Step 5 — Create the Project Folder Structure¶

Inside the repository, create the following folder structure. This matches the Technical Architecture Document exactly.

Run these commands in Git Bash from the repo root:

# Source code
mkdir -p src/autoloads
mkdir -p src/systems/simulation
mkdir -p src/systems/network
mkdir -p src/systems/save
mkdir -p src/systems/achievement
mkdir -p src/entities/buildings
mkdir -p src/entities/genesis
mkdir -p src/entities/belts
mkdir -p src/entities/aliens
mkdir -p src/entities/modules
mkdir -p src/ui/hud
mkdir -p src/ui/panels
mkdir -p src/ui/overlays
mkdir -p src/ui/menus

# Assets (art, audio, data)
mkdir -p assets/buildings/extraction
mkdir -p assets/buildings/processing
mkdir -p assets/buildings/logistics
mkdir -p assets/buildings/power
mkdir -p assets/buildings/storage
mkdir -p assets/buildings/research
mkdir -p assets/buildings/defence
mkdir -p assets/buildings/construction
mkdir -p assets/genesis
mkdir -p assets/terrain
mkdir -p assets/resources
mkdir -p assets/ui/icons
mkdir -p assets/ui/themes
mkdir -p assets/audio/music
mkdir -p assets/audio/sfx
mkdir -p assets/shaders

# Data resources (buildings, recipes, research nodes)
mkdir -p data/buildings
mkdir -p data/resources
mkdir -p data/recipes
mkdir -p data/research
mkdir -p data/achievements
mkdir -p data/factions
mkdir -p data/aliens

# Tests
mkdir -p tests/unit
mkdir -p tests/integration

# Documentation (your Obsidian vault goes here too if you want it tracked)
mkdir -p docs

# ============================================================
# Create .gitkeep files so empty folders are tracked by Git
# ============================================================
find . -type d -empty -not -path "./.git/*" -exec touch {}/.gitkeep \;

Step 6 — Create the Autoload Scripts¶

Create placeholder GDScript files for the four core autoloads defined in the Technical Architecture Document. These will be empty for now but need to exist so Godot can register them.

src/autoloads/GameManager.gd

# GameManager.gd
# Autoload — coordinates top-level game state
# Registered in Project Settings → Autoloads as "GameManager"
extends Node

func _ready() -> void:
    print("[GameManager] Initialised")

src/autoloads/NetworkManager.gd

# NetworkManager.gd
# Autoload — handles all multiplayer session logic
# Registered in Project Settings → Autoloads as "NetworkManager"
extends Node

func _ready() -> void:
    print("[NetworkManager] Initialised")

src/autoloads/AudioManager.gd

# AudioManager.gd
# Autoload — handles all audio bus management
# Registered in Project Settings → Autoloads as "AudioManager"
extends Node

func _ready() -> void:
    print("[AudioManager] Initialised")

src/autoloads/SaveManager.gd

# SaveManager.gd
# Autoload — handles session save and load
# Registered in Project Settings → Autoloads as "SaveManager"
extends Node

const SAVE_DIR := "user://saves/"

func _ready() -> void:
    DirAccess.make_dir_recursive_absolute(SAVE_DIR)
    print("[SaveManager] Initialised — save dir: %s" % SAVE_DIR)

After creating these files, register them in Godot: 1. Project → Project Settings → Autoloads 2. Add each file with the name matching the filename (without .gd)

Step 7 — Create the Branching Strategy¶

Auto Warz uses a simple two-branch strategy suited to solo development. No pull requests, no complex workflows — just clean separation between stable and in-progress work.

Branches¶

Branch	Purpose
`main`	Stable, always playable. Only merge here when a milestone is complete.
`dev`	Active development. All daily work happens here.

Optionally, create feature branches for large systems:

Branch	When to use
`feature/belt-system`	Building a whole new system from scratch
`feature/multiplayer`	Large multi-week effort (e.g. Phase 4)
`bugfix/save-corruption`	Fixing a specific bug found in main

Create the `dev` branch now:¶

git checkout -b dev

From this point, all daily development work happens on dev. Only merge to main when a milestone is fully complete and tested.

Step 8 — Commit Message Convention¶

Auto Warz uses Conventional Commits — a simple format that makes the git history readable and searchable.

Format¶

type(scope): short description

Optional longer description if needed.

Types¶

Type	Use for
`feat`	New feature or building/system added
`fix`	Bug fix
`refactor`	Code restructure (no behaviour change)
`perf`	Performance improvement
`art`	New or updated art asset
`data`	New or updated data resource (building def, recipe, etc.)
`docs`	Documentation update
`chore`	Tooling, config, dependencies
`test`	Adding or fixing tests

Scopes (Auto Warz specific)¶

Scope	Use for
`simulation`	Factory simulation tick system
`belts`	Belt system
`genesis`	Genesis bot
`network`	Multiplayer networking
`ui`	Any UI change
`buildings`	Building entities
`research`	Research system
`power`	Power system
`aliens`	Alien system
`modules`	Module system
`save`	Save/load system
`achievements`	Achievement system
`assets`	Art and audio assets

Examples¶

# Good commit messages
feat(genesis): implement manual move-to command
feat(belts): add basic belt placement and directional logic
fix(simulation): resolve tick rate drift at high entity counts
art(buildings): add Mining Drill voxel model and cel-shader material
data(buildings): define Mining Drill resource file with stats
refactor(network): extract RPC validation into BuildingValidator class
chore: update .gitignore to exclude Meshy temp files
docs: update Server Architecture Document with Genesis sync correction

# Bad commit messages (avoid these)
git commit -m "fix stuff"
git commit -m "changes"
git commit -m "wip"
git commit -m "asdfgh"

Why This Matters¶

In 6 months, you'll be able to run git log --oneline and instantly understand what changed and when. This is especially valuable when debugging regressions — "when did the belt system start breaking?" becomes a 10-second search instead of a guessing game.

Step 9 — Make the First Commit¶

Now commit everything we've set up:

# Make sure you're on the dev branch
git checkout dev

# Stage everything
git add .

# Check what's being committed (optional but recommended)
git status

# First commit
git commit -m "chore: initialise Auto Warz Godot 4 project

- Godot 4 project created with Forward+ renderer
- Godot-specific .gitignore configured
- Project folder structure matching Technical Architecture Document
- Autoload placeholder scripts created (GameManager, NetworkManager, AudioManager, SaveManager)
- dev branch established for active development"

# Push to GitHub
git push -u origin dev

Step 10 — Verify on GitHub¶

Go to github.com/YOUR_USERNAME/auto-warz
Switch to the dev branch using the branch dropdown
Confirm you can see:
src/ folder with autoload scripts
assets/ folder structure
data/ folder structure
.gitignore file
No .godot/ folder (this is the key check — if it's there, the .gitignore isn't working)

If .godot/ is visible, run:

git rm -r --cached .godot/
git commit -m "chore: remove .godot/ from tracking"
git push

Daily Development Workflow¶

Once setup is complete, your daily workflow is:

# Start of session — pull any changes (habit even when solo)
git pull

# Work on the game...

# End of session — commit what you've done
git add .
git status          # review what's being committed
git commit -m "feat(belts): implement basic belt item movement"
git push

# When a milestone is complete — merge to main
git checkout main
git merge dev
git push
git checkout dev    # go back to dev immediately

Commit Frequency¶

Commit at least once per development session
Commit whenever a discrete piece of work is done (placed a building, fixed a bug, added a resource file)
Never end a session with uncommitted work
Commits are free — make them often

Useful Git Commands (Quick Reference)¶

# See what's changed since last commit
git status

# See commit history (clean one-line view)
git log --oneline

# See what actually changed in files
git diff

# Undo changes to a specific file (before committing)
git checkout -- path/to/file.gd

# Undo last commit but keep the changes (oops, wrong message)
git reset --soft HEAD~1

# Create and switch to a new feature branch
git checkout -b feature/belt-system

# Switch back to dev
git checkout dev

# Merge a feature branch into dev when done
git checkout dev
git merge feature/belt-system

# Delete a feature branch after merging
git branch -d feature/belt-system

# Tag a milestone completion (useful for marking releases)
git tag -a "milestone/M1.7-prototype" -m "Prototype complete — first playable session loop"
git push --tags

Milestone Tagging¶

When you complete a Development Roadmap milestone, tag it:

git tag -a "milestone/M1.7-prototype-complete" -m "M1.7 done — 30 min playable session loop working"
git push --tags

This creates permanent markers in your git history you can always return to. If a future change breaks something that worked at the prototype, you can check out the tag and compare.

Open Questions / Setup Checklist¶

GitHub account created and repository exists at github.com/YOUR_USERNAME/auto-warz
Repository cloned locally
Godot 4 project created inside repository root
.gitignore created and .godot/ folder not tracked
Folder structure created
Autoload scripts created and registered in Godot Project Settings
dev branch created
First commit made and pushed to GitHub
Verified on GitHub — no .godot/ folder visible

Once this checklist is complete, you're ready to start M0.2 — Project Scaffolding from the Development Roadmap.