Backyard-CTF/docs/plans/2026-01-31-feat-unity-project-scaffold-plan.md

---
title: Unity 6 LTS Project Scaffold for Neighborhood Quarterback
type: feat
date: 2026-01-31
---

# Unity 6 LTS Project Scaffold for Neighborhood Quarterback

## Overview

Create the foundational Unity project structure for "Neighborhood Quarterback" - a 1v1 real-time capture-the-flag game. This scaffold establishes the correct Unity 6 LTS configuration, URP 2D rendering, New Input System, and cross-platform build targets (Android, iOS, Desktop).

**Brainstorm reference:** `docs/brainstorms/2026-01-31-unity-project-setup-brainstorm.md`

## Problem Statement

We need a properly configured Unity project foundation before any gameplay development can begin. Incorrect initial setup leads to painful refactoring later - especially render pipeline choices, input system selection, and mobile build configurations.

## Proposed Solution

Create a Unity 6 LTS project with:
- URP 2D Renderer for the "backyard baseball meets satellite-map clarity" aesthetic
- New Input System for unified touch/mouse handling
- Feature-based folder organization matching the game's system architecture
- Pre-configured build targets for all platforms

## Technical Approach

### Prerequisites

- Unity Hub installed
- Unity 6 LTS (6000.0.x or 6000.3.x) installed via Hub
- Android Build Support module (Android SDK, NDK, OpenJDK)
- iOS Build Support module (requires macOS + Xcode)

### Phase 1: Project Creation (Unity Hub)

**Task 1.1: Create new Unity project**

1. Open Unity Hub → Projects → New Project
2. Select "2D (URP)" template under Unity 6 LTS
3. Set project name: `neighborhood-quarterback`
4. Set location: `/Users/johnlamb/projects/backyard-ctf/`
5. Click Create

**Verification:** Project opens in Unity Editor with URP 2D configured.

### Phase 2: Package Configuration

**Task 2.1: Verify/Install required packages**

Open Window → Package Manager and ensure these are installed:

| Package | Purpose |
|---------|---------|
| Universal RP | Already included with 2D URP template |
| Input System | Cross-platform input (install if not present) |
| 2D Sprite | Sprite rendering (should be included) |
| 2D Tilemap | Optional - for map building later |

**Task 2.2: Configure Input System**

1. Edit → Project Settings → Player → Other Settings
2. Set "Active Input Handling" to **Input System Package (New)**
3. Restart Unity when prompted

**Verification:** `Packages/manifest.json` contains `"com.unity.inputsystem"`.

### Phase 3: Folder Structure Setup

**Task 3.1: Create feature-based folder structure**

In the Project window, create this hierarchy under `Assets/`:

```
Assets/
├── Features/
│   └── _Template/
│       └── README.txt           # "Copy this folder for new features"
├── Shared/
│   ├── Fonts/
│   └── UI/
├── Settings/
│   ├── URP/                     # Move URP assets here
│   └── Input/                   # Input action assets go here
└── Scenes/
    └── Main.unity               # Rename SampleScene or create new
```

**Task 3.2: Organize URP settings**

1. Locate the URP assets created by template (usually in `Assets/Settings/` or root)
2. Move `URP-2D-Renderer.asset` and `URP-2D.asset` to `Assets/Settings/URP/`
3. Update references in Edit → Project Settings → Graphics if needed

**Task 3.3: Create placeholder Input Actions**

1. Right-click `Assets/Settings/Input/` → Create → Input Actions
2. Name it `GameInputActions`
3. Open and create initial action map "Gameplay" with placeholder actions:
   - `Select` (Button) - for unit selection
   - `Point` (Value, Vector2) - for cursor/touch position
   - `Drag` (Button) - for route drawing

**Verification:** Folder structure matches spec, no broken asset references.

### Phase 4: Build Target Configuration

**Task 4.1: Add Android platform**

1. File → Build Settings
2. Select Android → Switch Platform
3. Player Settings → Other Settings:
   - Scripting Backend: **IL2CPP**
   - Target Architectures: **ARM64** only
   - Minimum API Level: **Android 7.0 (API 24)**
   - Target API Level: **Automatic (highest)**

**Task 4.2: Add iOS platform**

1. File → Build Settings
2. Select iOS → Switch Platform
3. Player Settings → Other Settings:
   - Scripting Backend: **IL2CPP** (required for iOS)
   - Target SDK: **Device SDK**
   - Target minimum iOS Version: **13.0**
   - Architecture: **ARM64**

**Task 4.3: Configure Desktop platforms**

1. File → Build Settings
2. Select Windows/Mac/Linux → Switch Platform
3. Player Settings → Other Settings:
   - Scripting Backend: **Mono** (faster iteration) or **IL2CPP** (release)
   - Architecture: **x86_64** / **Apple Silicon + Intel**

**Task 4.4: Configure common Player Settings**

1. Edit → Project Settings → Player
2. Set Company Name: (your company)
3. Set Product Name: `Neighborhood Quarterback`
4. Set Default Icon: (can add later)
5. Under Resolution and Presentation:
   - Orientation: **Landscape Left** or **Auto Rotation** (landscape modes only)

**Verification:** Build Settings shows all platforms configured. Test builds to each target (at least to build step, not full deploy).

### Phase 5: URP 2D Renderer Configuration

**Task 5.1: Configure 2D Renderer for night aesthetic**

1. Open `Assets/Settings/URP/URP-2D-Renderer.asset`
2. Enable **Light2D** in Renderer Features (should be default)
3. Verify HDR is enabled in URP Asset for bloom effects later

**Task 5.2: Create Main scene with proper lighting**

1. Open/Create `Assets/Scenes/Main.unity`
2. Add a Global Light 2D (GameObject → 2D Object → Light → Global Light 2D)
3. Set intensity low (~0.1-0.2) for "night" base lighting
4. This allows adding spotlights later for motion lights

**Verification:** Scene has dark ambient with Global Light 2D.

### Phase 6: Git Configuration

**Task 6.1: Create Unity-appropriate .gitignore**

Create `.gitignore` at project root:

```gitignore
# Unity generated
[Ll]ibrary/
[Tt]emp/
[Oo]bj/
[Bb]uild/
[Bb]uilds/
[Ll]ogs/
[Uu]ser[Ss]ettings/

# MemoryCaptures
[Mm]emoryCaptures/

# Recordings
[Rr]ecordings/

# Asset meta data should be tracked
!*.meta

# Autogenerated VS/Rider
.vsconfig
*.csproj
*.unityproj
*.sln
*.suo
*.tmp
*.user
*.userprefs
*.pidb
*.booproj
*.svd
*.pdb
*.mdb
*.opendb
*.VC.db

# Unity3D generated meta files
*.pidb.meta
*.pdb.meta
*.mdb.meta

# Builds
*.apk
*.aab
*.unitypackage
*.app

# Crashlytics
crashlytics-build.properties

# Packed Addressables
[Aa]ddressables*.bin*

# TextMeshPro
[Aa]ssets/TextMesh*Pro/Resources/Fonts & Materials/*.asset

# macOS
.DS_Store
```

**Task 6.2: Configure Unity for version control**

1. Edit → Project Settings → Editor
2. Version Control Mode: **Visible Meta Files**
3. Asset Serialization Mode: **Force Text**

**Task 6.3: Initial commit**

```bash
git init
git add .
git commit -m "feat: Initialize Unity 6 LTS project with URP 2D scaffold

- Unity 6 LTS with URP 2D Renderer
- New Input System configured
- Feature-based folder structure
- Build targets: Android (ARM64), iOS (ARM64), Desktop
- Night lighting setup for game aesthetic

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
```

**Verification:** `git status` shows clean working tree.

## Acceptance Criteria

- [ ] Unity 6 LTS project opens without errors
- [ ] URP 2D Renderer is active (check Graphics settings)
- [ ] New Input System is the active input handling mode
- [ ] Folder structure matches spec (`Features/`, `Shared/`, `Settings/`, `Scenes/`)
- [ ] `GameInputActions` asset exists with placeholder actions
- [ ] Android build target configured (IL2CPP, ARM64, API 24+)
- [ ] iOS build target configured (IL2CPP, ARM64, iOS 13+)
- [ ] Desktop build targets configured
- [ ] Main.unity scene has Global Light 2D with low intensity
- [ ] `.gitignore` excludes Library/, Temp/, builds
- [ ] Project uses text-based asset serialization
- [ ] Initial git commit created

## Files Created/Modified

| File | Purpose |
|------|---------|
| `Assets/Features/_Template/README.txt` | Template folder for new features |
| `Assets/Shared/Fonts/.gitkeep` | Fonts placeholder |
| `Assets/Shared/UI/.gitkeep` | UI placeholder |
| `Assets/Settings/URP/*.asset` | URP configuration |
| `Assets/Settings/Input/GameInputActions.inputactions` | Input action definitions |
| `Assets/Scenes/Main.unity` | Entry scene |
| `Packages/manifest.json` | Package dependencies |
| `ProjectSettings/*.asset` | Unity project settings (auto-generated) |
| `.gitignore` | Git ignore rules |

## Implementation Notes

**Why IL2CPP for mobile:** Required for iOS, strongly recommended for Android performance. Use Mono on desktop during development for faster iteration.

**Why ARM64 only for Android:** ARMv7 devices are <5% of market in 2026. ARM64-only reduces build size and maintenance.

**Why API 24 minimum:** Android 7.0 has 99%+ coverage, provides modern APIs, supports Vulkan.

**Why feature-based folders:** The soul doc identifies distinct systems (FogOfWar, Jail, Units, MotionLights). Feature-based organization keeps related code, prefabs, and art together.

## References

- [Unity 6.3 LTS Release Notes](https://omitram.com/unity-6-3-lts-6000-3-0f1-full-release-notes-breakdown/)
- [Unity Input System](https://unity.com/features/input-system)
- [URP for Mobile](https://unity.com/games/urp)
- [Unity Cross-Platform Considerations](https://docs.unity3d.com/6000.2/Documentation/Manual/CrossPlatformConsiderations.html)
- Brainstorm: `docs/brainstorms/2026-01-31-unity-project-setup-brainstorm.md`
- Soul Doc: `soul.md`