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

title, type, date

title	type	date
Unity 6 LTS Project Scaffold for Neighborhood Quarterback	feat	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:

# 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

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+) - partially configured, UI differs from plan
• [~] iOS build target configured (IL2CPP, ARM64, iOS 13+) - partially configured, UI differs from plan
• Desktop build targets configured
• Main.unity scene has Global Light 2D with low intensity - TODO: add in Unity Editor
• .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
• Unity Input System
• URP for Mobile
• Unity Cross-Platform Considerations
• Brainstorm: docs/brainstorms/2026-01-31-unity-project-setup-brainstorm.md
• Soul Doc: soul.md