Upload folder using huggingface_hub

README.md

@@ -0,0 +1,254 @@
+# Unity Agent
+
+A Python package that generates complete, playable **Unity 2022.3 LTS**
+projects on disk. The agent exposes a registry of code-generation tools
+that emit C# scripts (MonoBehaviours), `.unity` scene files, project
+configuration (manifest, ProjectSettings, .meta) and a full open-world
+city example game. The output is a real Unity project you can open in
+Unity Hub and press Play.
+
+## What it does
+
+* Writes complete, compilable **C#** MonoBehaviours (player, vehicle,
+  camera, AI, weapons, inventory, quests, save system, ...).
+* Scaffolds a Unity project structure (`Assets/`, `Packages/manifest.json`,
+  `ProjectSettings/`, `.meta` files) exactly the way Unity expects.
+* Provides a **system prompt** that teaches an LLM to act like a senior
+  Unity engineer and to call the right tool in the right order.
+* Ships a **knowledge base** of focused markdown references
+  (physics, navigation, input, UI, audio, rendering, open-world design).
+* Runs **static QA** against generated projects to catch unbalanced
+  braces, missing meta files, missing manifest, etc.
+* Comes with a fully working **open-world city example** generated
+  end-to-end from the tool layer.
+
+## Installation
+
+```bash
+git clone <this-repo> unity-agent
+cd unity-agent
+pip install -e .            # optional; the package also works with PYTHONPATH=.
+```
+
+The package has **no third-party Python dependencies** -- it only uses the
+standard library. Python 3.9+ is required.
+
+## Quick start
+
+### Generate the bundled example
+
+```bash
+# Generate the full open-world city example into examples/open_world_city/
+python -m unity_agent generate --game open_world_city --preset open_world_city --output-dir examples
+
+# Run static QA on it
+python -m unity_agent qa examples/open_world_city
+```
+
+Open `examples/open_world_city/` in Unity Hub (2022.3 LTS or newer) and
+press Play.
+
+### Use the package from Python
+
+```python
+from unity_agent.config import Settings
+from unity_agent.transport.unity_transport import UnityTransport
+from unity_agent.tools.unity_tools import (
+    SetupUnityProjectTool,
+    CreatePlayerControllerTool,
+    CreateProceduralCityTool,
+    WriteSceneFileTool,
+)
+
+settings = Settings(output_dir="my_games")
+transport = UnityTransport(settings)
+
+SetupUnityProjectTool(settings, transport).run(project_name="MyGame")
+CreatePlayerControllerTool(settings, transport).run(project_name="MyGame")
+CreateProceduralCityTool(settings, transport).run(project_name="MyGame")
+WriteSceneFileTool(settings, transport).run(project_name="MyGame", scene_name="MainScene")
+
+print(transport.summary())
+```
+
+### CLI
+
+```bash
+python -m unity_agent --help
+
+# Commands
+python -m unity_agent list-tools
+python -m unity_agent setup --project-name MyGame --output-dir my_games
+python -m unity_agent generate --game MyGame --preset open_world_city
+python -m unity_agent generate --game MyFPS --preset fps_arena
+python -m unity_agent generate --game Minimal --preset minimal
+python -m unity_agent qa path/to/MyGame
+```
+
+## Project layout
+
+```
+unity-agent/
+  unity_agent/
+    __init__.py              # Package entry point
+    __main__.py              # CLI: `python -m unity_agent ...`
+    config.py                # Settings (Unity path, LLM keys, output dirs)
+    tests.py                 # Self-test suite (run with `python -m unity_agent.tests`)
+    transport/
+      __init__.py
+      unity_transport.py     # Writes .cs / .unity / .meta / config files
+    tools/
+      __init__.py
+      base.py                # ToolBase + ToolRegistry + @register_tool
+      unity_tools.py         # 24 tools (see below)
+    orchestrator/
+      __init__.py
+      prompts.py             # SYSTEM_PROMPT + build_user_prompt + tool_catalog
+    knowledge/
+      README.md
+      __init__.py            # load_entry / list_entries / load_all
+      entries/
+        unity_fundamentals.md
+        unity_physics.md
+        unity_rendering.md
+        unity_navigation.md
+        unity_input_system.md
+        unity_ui.md
+        unity_audio.md
+        open_world_design.md
+    qa/
+      __init__.py            # ProjectQA + Issue + QAReport + CLI
+  examples/
+    generate_example.py      # Regenerates examples/open_world_city/
+    open_world_city/         # A complete generated Unity project
+      Assets/Scripts/*.cs
+      Assets/Scenes/MainScene.unity
+      Packages/manifest.json
+      ProjectSettings/*
+      README.md
+  pyproject.toml
+  README.md
+```
+
+## Tools (24 total)
+
+| Tool                          | Output                                                       |
+|-------------------------------|--------------------------------------------------------------|
+| `setup_unity_project`         | Project scaffold (manifest, ProjectSettings, asmdef)         |
+| `create_player_controller`    | PlayerController.cs (WASD + jump + physics)                  |
+| `create_vehicle_controller`   | VehicleController.cs (arcade car physics)                    |
+| `create_procedural_city`      | CityGenerator.cs + BuildingGenerator.cs (50+ buildings)      |
+| `create_third_person_camera`  | ThirdPersonCamera.cs (smooth follow + collision)             |
+| `create_fps_controller`       | FPSController.cs (mouse-look + WASD + jump)                  |
+| `create_day_night_cycle`      | DayNightCycle.cs (sun rotation + sky/ambient lerp)           |
+| `create_ai_npc`               | NPCController.cs (NavMesh wander/chase FSM)                  |
+| `create_pickup_system`        | PickupSystem.cs + Pickup.cs (score + collectibles)           |
+| `create_health_system`        | HealthSystem.cs + HealthBar.cs                               |
+| `create_weapon_system`        | WeaponSystem.cs (raycast hitscan + ammo + reload)            |
+| `create_audio_manager`        | AudioManager.cs (SFX + music singleton)                      |
+| `create_ui_manager`           | UIManager.cs (TMP HUD: score / health / messages)            |
+| `create_terrain_generator`    | TerrainGenerator.cs (Perlin heightmap + splat)               |
+| `create_water_shader`         | WaterMaterial.cs (animated standard-material water)          |
+| `create_particle_effects`     | ParticleSpawner.cs (bursts + explosion helper)               |
+| `create_save_system`          | SaveSystem.cs (JSON save/load to persistentDataPath)         |
+| `create_inventory_system`     | InventorySystem.cs (stacks + capacity + events)              |
+| `create_quest_system`         | QuestSystem.cs (state machine + progress + completion)       |
+| `create_building_generator`   | BuildingGenerator.cs (walls + emissive windows + collider)   |
+| `create_road_network`         | RoadNetwork.cs (grid layout + intersections)                 |
+| `write_csharp_script`         | Any C# script to Assets/Scripts/                             |
+| `write_scene_file`            | .unity scene file to Assets/Scenes/                          |
+| `generate_complete_game`      | Full game in one call (presets: open_world_city, fps_arena, minimal) |
+
+## The system prompt
+
+`unity_agent.orchestrator.prompts.SYSTEM_PROMPT` is a long, prescriptive
+prompt that teaches the LLM to:
+
+* Think like a senior Unity engineer (lifecycle, physics step, idiomatic
+  C#).
+* Know the tool catalog and the recommended workflow (scaffold ->
+  components -> bootstrap script -> scene).
+* Always emit code that compiles on the first try in Unity 2022.3 LTS.
+* Prefer procedural content (runtime `Start()` generation) over
+  inspector-wired prefabs so the example "just plays" on open.
+* Use the `UnityAgent` namespace and the `UnityAgent.Scripts` asmdef.
+
+Use it like this from your own LLM driver:
+
+```python
+from unity_agent.orchestrator import SYSTEM_PROMPT, build_user_prompt
+
+prompt = build_user_prompt("Build me an open-world city game I can drive around in")
+# Send SYSTEM_PROMPT + prompt to your LLM, then dispatch tool calls.
+```
+
+## Knowledge base
+
+Eight focused markdown references in `unity_agent/knowledge/entries/`:
+
+1. `unity_fundamentals.md` -- MonoBehaviour lifecycle, GameObjects,
+   components, coroutines, inspector best practices.
+2. `unity_physics.md` -- Rigidbody, colliders, raycasting, ForceModes,
+   physics vs frame step.
+3. `unity_rendering.md` -- Materials, Standard shader, lighting, post-
+   processing, LOD, fog.
+4. `unity_navigation.md` -- NavMesh, NavMeshAgent, AI state machines,
+   NavMeshObstacle, off-mesh links.
+5. `unity_input_system.md` -- Legacy Input Manager, mouse-look recipes,
+   new Input System, touch.
+6. `unity_ui.md` -- Canvas, anchoring, HUD pattern, TMP, performance.
+7. `unity_audio.md` -- AudioSource, 3D audio, AudioMixer, AudioManager
+   singleton.
+8. `open_world_design.md` -- Procedural generation, LOD, streaming,
+   day/night cycle, save systems.
+
+Load them programmatically:
+
+```python
+from unity_agent.knowledge import list_entries, load_entry, load_all
+
+for slug in list_entries():
+    print(slug, len(load_entry(slug)))
+```
+
+## QA
+
+`unity_agent.qa.ProjectQA` runs static checks against a generated project:
+
+* Required directories exist (`Assets/`, `Assets/Scripts/`, `Packages/`,
+  `ProjectSettings/`).
+* Required files exist (`Packages/manifest.json`,
+  `ProjectSettings/ProjectVersion.txt`,
+  `ProjectSettings/ProjectSettings.asset`).
+* Every `.cs` file has balanced braces and at least one type declaration.
+* Every `.cs` and `.unity` file has a sibling `.meta`.
+* Scene files start with the `%YAML` header.
+* `manifest.json` parses as JSON and has a `dependencies` object.
+
+```python
+from unity_agent.qa import ProjectQA
+report = ProjectQA("examples/open_world_city").run()
+print(report.summary())
+print("PASS" if report.passed else "FAIL")
+```
+
+## Tests
+
+```bash
+python -m unity_agent.tests
+```
+
+Verifies the tool registry has 24 entries, the project scaffolder writes
+the expected files, generated C# has balanced braces, the full game
+generator produces 12+ scripts, and QA passes on a freshly generated
+project.
+
+## Requirements
+
+* Python 3.9+ (no third-party dependencies).
+* Unity Hub + Unity 2022.3 LTS (or newer) to actually open and play the
+  generated projects. The Python layer works without Unity installed.
+
+## License
+
+MIT.

examples/generate_example.py

@@ -0,0 +1,78 @@
+"""Regenerate the open_world_city example using the unity_agent package.
+
+Usage::
+
+    python examples/generate_example.py
+
+This re-creates ``examples/open_world_city/`` from scratch using the same
+tool chain the orchestrator would use.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Make the package importable when run directly.
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+from unity_agent.config import Settings
+from unity_agent.transport.unity_transport import UnityTransport
+from unity_agent.tools.unity_tools import (
+    GenerateCompleteGameTool,
+    WriteCSharpScriptTool,
+)
+from unity_agent.qa import ProjectQA
+
+
+CAMERA_CONTROLLER_CS = """\
+using UnityEngine;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// Convenience alias for <see cref="ThirdPersonCamera"/>. Lets designers
+    /// attach a component named CameraController if they prefer that name.
+    /// </summary>
+    public class CameraController : ThirdPersonCamera
+    {
+        // All behaviour is inherited from ThirdPersonCamera.
+    }
+}
+"""
+
+
+def main() -> int:
+    examples_dir = ROOT / "examples"
+    settings = Settings(output_dir=str(examples_dir), product_name="open_world_city")
+    transport = UnityTransport(settings)
+    transport.open_project("open_world_city")
+
+    # Clear the destination so we always start fresh.
+    import shutil
+    if (examples_dir / "open_world_city").exists():
+        shutil.rmtree(examples_dir / "open_world_city")
+    transport.open_project("open_world_city")
+
+    result = GenerateCompleteGameTool(settings, transport).run(
+        game_name="open_world_city", preset="open_world_city",
+        project_name="open_world_city",
+    )
+    print(result.summary)
+
+    # Add the CameraController alias the user spec asks for.
+    cam_result = WriteCSharpScriptTool(settings, transport).run(
+        filename="CameraController.cs", code=CAMERA_CONTROLLER_CS,
+        project_name="open_world_city",
+    )
+    print(cam_result.summary)
+
+    # QA the result.
+    report = ProjectQA(examples_dir / "open_world_city").run()
+    print(report.summary())
+    return 0 if report.passed else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

examples/open_world_city/Assets/Scenes/MainScene.unity

@@ -0,0 +1,101 @@
+%YAML 1.1
+%TAG !u! tag:unity3d.com,2011:
+--- !u!29 &1
+OcclusionCullingSettings:
+  m_ObjectHideFlags: 0
+  serializedVersion: 2
+  m_OcclusionBakeSettings:
+    smallestOccluder: 5
+    smallestHole: 0.25
+    backfaceThreshold: 100
+  m_SceneGUID: 00000000000000000000000000000000
+  m_OcclusionCullingData: {fileID: 0}
+--- !u!104 &2
+RenderSettings:
+  m_ObjectHideFlags: 0
+  serializedVersion: 9
+  m_Fog: 0
+  m_FogColor: {r: 0.5, g: 0.5, b: 0.5, a: 1}
+  m_FogMode: 3
+  m_FogDensity: 0.01
+  m_LinearFogStart: 0
+  m_LinearFogEnd: 300
+  m_AmbientSkyColor: {r: 0.4, g: 0.4, b: 0.4, a: 1}
+  m_AmbientEquatorColor: {r: 0.2, g: 0.2, b: 0.2, a: 1}
+  m_AmbientGroundColor: {r: 0.1, g: 0.1, b: 0.1, a: 1}
+  m_AmbientIntensity: 1
+  m_AmbientMode: 0
+  m_SubtractiveShadowColor: {r: 0.2, g: 0.2, b: 0.2, a: 1}
+  m_SkyboxMaterial: {fileID: 0}
+  m_HaloStrength: 0.5
+  m_FlareStrength: 1
+  m_FlareFadeSpeed: 3
+  m_HaloTexture: {fileID: 0}
+  m_SpotCookie: {fileID: 0}
+  m_DefaultReflectionMode: 0
+  m_DefaultReflectionResolution: 128
+  m_ReflectionBounces: 1
+  m_ReflectionIntensity: 1
+  m_CustomReflection: {fileID: 0}
+  m_Sun: {fileID: 0}
+  m_IndirectSpecularColor: {r: 0, g: 0, b: 0, a: 1}
+  m_UseRadianceAmbientProbe: 0
+--- !u!157 &3
+LightmapSettings:
+  m_ObjectHideFlags: 0
+  serializedVersion: 12
+  m_GIWorkflowMode: 0
+  m_EnableBakedLightmaps: 1
+  m_EnableRealtimeLightmaps: 0
+--- !u!196 &4
+NavMeshSettings:
+  m_ObjectHideFlags: 0
+  serializedVersion: 2
+  m_AutoGenerate: 0
+--- !u!1 &100
+GameObject:
+  m_ObjectHideFlags: 0
+  m_Name: Main Camera
+  m_IsActive: 1
+  m_Component:
+  - component: {fileID: 101}
+  - component: {fileID: 102}
+  m_Layer: 0
+--- !u!4 &101
+Transform:
+  m_GameObject: {fileID: 100}
+  m_LocalPosition: {x: 0, y: 5, z: -10}
+  m_LocalRotation: {x: 0, y: 0, z: 0, w: 1}
+  m_LocalScale: {x: 1, y: 1, z: 1}
+--- !u!20 &102
+Camera:
+  m_GameObject: {fileID: 100}
+  m_ClearFlags: 1
+  m_BackGroundColor: {r: 0.4, g: 0.6, b: 0.9, a: 1}
+  m_Orthographic: 0
+  m_FieldOfView: 60
+  m_NearClipPlane: 0.3
+  m_FarClipPlane: 1000
+--- !u!1 &200
+GameObject:
+  m_ObjectHideFlags: 0
+  m_Name: Directional Light
+  m_IsActive: 1
+  m_Component:
+  - component: {fileID: 201}
+  - component: {fileID: 202}
+  m_Layer: 0
+--- !u!4 &201
+Transform:
+  m_GameObject: {fileID: 200}
+  m_LocalRotation: {x: 0.4, y: -0.3, z: 0.2, w: 0.8}
+  m_LocalPosition: {x: 0, y: 50, z: 0}
+  m_LocalScale: {x: 1, y: 1, z: 1}
+--- !u!108 &202
+Light:
+  m_GameObject: {fileID: 200}
+  m_Type: 1
+  m_Color: {r: 1, g: 1, b: 1, a: 1}
+  m_Intensity: 1
+  m_Shadows:
+    m_Type: 2

examples/open_world_city/Assets/Scenes/MainScene.unity.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 8a32e127d322fab3b2c0affc00e372cd
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/AudioManager.cs

@@ -0,0 +1,67 @@
+using UnityEngine;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// Singleton audio manager that exposes named one-shot SFX and music
+    /// channels. Used by other systems to play clips without having to manage
+    /// their own AudioSource components.
+    /// </summary>
+    public class AudioManager : MonoBehaviour
+    {
+        public static AudioManager Instance { get; private set; }
+
+        [Header("Mixers")]
+        public AudioSource sfxSource;
+        public AudioSource musicSource;
+
+        [Range(0f, 1f)] public float masterVolume = 1f;
+        [Range(0f, 1f)] public float sfxVolume = 0.8f;
+        [Range(0f, 1f)] public float musicVolume = 0.5f;
+
+        private void Awake()
+        {
+            if (Instance != null && Instance != this) { Destroy(gameObject); return; }
+            Instance = this;
+            DontDestroyOnLoad(gameObject);
+
+            if (sfxSource == null)
+            {
+                sfxSource = gameObject.AddComponent<AudioSource>();
+                sfxSource.playOnAwake = false;
+            }
+            if (musicSource == null)
+            {
+                musicSource = gameObject.AddComponent<AudioSource>();
+                musicSource.loop = true;
+                musicSource.playOnAwake = false;
+            }
+            ApplyVolumes();
+        }
+
+        public void PlaySfx(AudioClip clip, float volumeScale = 1f)
+        {
+            if (clip != null && sfxSource != null)
+                sfxSource.PlayOneShot(clip, volumeScale * sfxVolume * masterVolume);
+        }
+
+        public void PlayMusic(AudioClip clip)
+        {
+            if (clip == null || musicSource == null) return;
+            musicSource.clip = clip;
+            musicSource.volume = musicVolume * masterVolume;
+            musicSource.Play();
+        }
+
+        public void StopMusic()
+        {
+            if (musicSource != null) musicSource.Stop();
+        }
+
+        public void ApplyVolumes()
+        {
+            if (musicSource != null) musicSource.volume = musicVolume * masterVolume;
+            AudioListener.volume = masterVolume;
+        }
+    }
+}

examples/open_world_city/Assets/Scripts/AudioManager.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 803745e8c679b595410a0a143b1abc48
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/BuildingGenerator.cs

@@ -0,0 +1,68 @@
+using UnityEngine;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// Procedural building generator: builds a box building mesh with
+    /// emissive windows and adds a BoxCollider for collision.
+    /// </summary>
+    public static class BuildingGenerator
+    {
+        public static GameObject Generate(string name, Vector3 position, Vector3 size,
+                                          Material wallMaterial, Material windowMaterial)
+        {
+            GameObject go = new GameObject(name);
+            go.transform.position = position;
+
+            // Walls
+            GameObject walls = GameObject.CreatePrimitive(PrimitiveType.Cube);
+            walls.name = "Walls";
+            walls.transform.SetParent(go.transform, false);
+            walls.transform.localScale = size;
+            walls.transform.localPosition = Vector3.up * size.y * 0.5f;
+            if (wallMaterial != null) walls.GetComponent<MeshRenderer>().sharedMaterial = wallMaterial;
+
+            // Windows: a smaller cube with the window material, slightly offset on each side.
+            if (windowMaterial != null)
+            {
+                GameObject windows = GameObject.CreatePrimitive(PrimitiveType.Cube);
+                windows.name = "Windows";
+                windows.transform.SetParent(go.transform, false);
+                windows.transform.localScale = size * 0.99f;
+                windows.transform.localPosition = Vector3.up * size.y * 0.5f;
+                var mr = windows.GetComponent<MeshRenderer>();
+                mr.sharedMaterial = windowMaterial;
+            }
+
+            // Collider (the cube already has one, but ensure it's a BoxCollider).
+            var box = go.GetComponent<BoxCollider>();
+            if (box == null) box = go.AddComponent<BoxCollider>();
+            box.size = size;
+            box.center = Vector3.up * size.y * 0.5f;
+
+            return go;
+        }
+
+        /// <summary>
+        /// Build an emissive window material procedurally so the agent does
+        /// not depend on any asset on disk.
+        /// </summary>
+        public static Material MakeWindowMaterial(Color glow)
+        {
+            var m = new Material(Shader.Find("Standard"));
+            m.name = "WindowMat";
+            m.color = Color.black;
+            m.SetColor("_EmissionColor", glow);
+            m.EnableKeyword("_EMISSION");
+            return m;
+        }
+
+        public static Material MakeWallMaterial(Color col)
+        {
+            var m = new Material(Shader.Find("Standard"));
+            m.name = "WallMat";
+            m.color = col;
+            return m;
+        }
+    }
+}

examples/open_world_city/Assets/Scripts/BuildingGenerator.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 720373d252ebafade9462c2ee8876f1c
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/CameraController.cs

@@ -0,0 +1,13 @@
+using UnityEngine;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// Convenience alias for <see cref="ThirdPersonCamera"/>. Lets designers
+    /// attach a component named CameraController if they prefer that name.
+    /// </summary>
+    public class CameraController : ThirdPersonCamera
+    {
+        // All behaviour is inherited from ThirdPersonCamera.
+    }
+}

examples/open_world_city/Assets/Scripts/CameraController.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 34509a07673ea2c5921f70e933984b60
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/CityGenerator.cs

@@ -0,0 +1,110 @@
+using UnityEngine;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// Procedural city generator: spawns a grid of buildings of varying
+    /// heights with emissive windows, street lights and parked vehicles.
+    /// Designed to be paired with <see cref="RoadNetwork"/>.
+    /// </summary>
+    public class CityGenerator : MonoBehaviour
+    {
+        [Header("Grid")]
+        public int gridX = 8;
+        public int gridZ = 8;
+        public float blockSpacing = 30f;
+
+        [Header("Buildings")]
+        public int buildingsPerBlock = 1;
+        public float minBuildingHeight = 8f;
+        public float maxBuildingHeight = 40f;
+        public float buildingFootprint = 8f;
+        public Color wallColor = new Color(0.4f, 0.4f, 0.42f);
+        public Color windowColor = new Color(1.0f, 0.85f, 0.4f);
+
+        [Header("Street Lights")]
+        public bool spawnStreetLights = true;
+        public float lightSpacing = 15f;
+        public Color lightColor = new Color(1.0f, 0.85f, 0.5f);
+        public float lightIntensity = 1.5f;
+        public float lightRange = 15f;
+
+        private readonly System.Collections.Generic.List<Light> _lights = new System.Collections.Generic.List<Light>();
+
+        private void Start()
+        {
+            Generate();
+        }
+
+        public void Generate()
+        {
+            Material wallMat = BuildingGenerator.MakeWallMaterial(wallColor);
+            Material winMat = BuildingGenerator.MakeWindowMaterial(windowColor);
+
+            float totalX = (gridX - 1) * blockSpacing;
+            float totalZ = (gridZ - 1) * blockSpacing;
+            Vector3 origin = transform.position - new Vector3(totalX * 0.5f, 0f, totalZ * 0.5f);
+
+            for (int x = 0; x < gridX; x++)
+            {
+                for (int z = 0; z < gridZ; z++)
+                {
+                    Vector3 block = new Vector3(origin.x + x * blockSpacing, 0f, origin.z + z * blockSpacing);
+                    SpawnBlock(block, wallMat, winMat);
+                }
+            }
+
+            if (spawnStreetLights) SpawnStreetLights(origin, totalX, totalZ);
+        }
+
+        private void SpawnBlock(Vector3 center, Material wallMat, Material winMat)
+        {
+            for (int i = 0; i < buildingsPerBlock; i++)
+            {
+                float h = Random.Range(minBuildingHeight, maxBuildingHeight);
+                Vector3 size = new Vector3(buildingFootprint, h, buildingFootprint);
+                Vector3 pos = center + new Vector3(
+                    Random.Range(-4f, 4f), 0f, Random.Range(-4f, 4f));
+                BuildingGenerator.Generate($"Building_{center.x}_{center.z}_{i}", pos, size, wallMat, winMat);
+            }
+        }
+
+        private void SpawnStreetLights(Vector3 origin, float totalX, float totalZ)
+        {
+            Material poleMat = BuildingGenerator.MakeWallMaterial(new Color(0.1f, 0.1f, 0.1f));
+
+            for (float x = origin.x; x <= origin.x + totalX + 0.1f; x += lightSpacing)
+            {
+                for (float z = origin.z; z <= origin.z + totalZ + 0.1f; z += lightSpacing)
+                {
+                    SpawnStreetLight(new Vector3(x, 0f, z), poleMat);
+                }
+            }
+        }
+
+        private void SpawnStreetLight(Vector3 pos, Material poleMat)
+        {
+            GameObject pole = GameObject.CreatePrimitive(PrimitiveType.Cylinder);
+            pole.name = "StreetLight";
+            pole.transform.SetParent(transform, false);
+            pole.transform.position = pos + Vector3.up * 4f;
+            pole.transform.localScale = new Vector3(0.2f, 4f, 0.2f);
+            pole.GetComponent<MeshRenderer>().sharedMaterial = poleMat;
+
+            GameObject bulb = GameObject.CreatePrimitive(PrimitiveType.Sphere);
+            bulb.transform.SetParent(pole.transform, false);
+            bulb.transform.localPosition = Vector3.up * 0.9f;
+            bulb.transform.localScale = Vector3.one * 0.4f;
+            bulb.GetComponent<MeshRenderer>().sharedMaterial = BuildingGenerator.MakeWindowMaterial(lightColor);
+
+            Light l = bulb.AddComponent<Light>();
+            l.type = LightType.Point;
+            l.color = lightColor;
+            l.intensity = lightIntensity;
+            l.range = lightRange;
+            _lights.Add(l);
+        }
+
+        public Light[] StreetLights => _lights.ToArray();
+    }
+}

examples/open_world_city/Assets/Scripts/CityGenerator.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: a1590f0f60a74829eaa91c784094575b
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/DayNightCycle.cs

@@ -0,0 +1,69 @@
+using UnityEngine;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// Rotates a directional light around the world to simulate a day/night
+    /// cycle. Also lerps between day and night sky/ambient colors and turns
+    /// street lights on after sunset.
+    /// </summary>
+    public class DayNightCycle : MonoBehaviour
+    {
+        [Header("Sun")]
+        public Light sun;
+        public float dayLengthSeconds = 120f;
+
+        [Header("Colors")]
+        public Color daySky = new Color(0.5f, 0.7f, 1.0f);
+        public Color nightSky = new Color(0.03f, 0.04f, 0.08f);
+        public Color dayAmbient = new Color(0.6f, 0.6f, 0.6f);
+        public Color nightAmbient = new Color(0.12f, 0.13f, 0.18f);
+
+        [Header("Lights")]
+        public Light[] streetLights;
+        public float streetLightThreshold = 0.2f;
+
+        private float _timeOfDay; // 0..1
+
+        private void Start()
+        {
+            if (sun == null) sun = GetComponent<Light>();
+            RenderSettings.ambientMode = UnityEngine.Rendering.AmbientMode.Flat;
+        }
+
+        private void Update()
+        {
+            _timeOfDay = (_timeOfDay + Time.deltaTime / dayLengthSeconds) % 1f;
+
+            // Sun angle: at timeOfDay=0.25 sun is at noon.
+            float sunAngle = (_timeOfDay - 0.25f) * 360f;
+            if (sun != null)
+            {
+                sun.transform.rotation = Quaternion.Euler(sunAngle, -30f, 0f);
+                float dayFactor = Mathf.Clamp01(Mathf.Cos((_timeOfDay - 0.25f) * Mathf.PI * 2f) * 0.5f + 0.5f);
+                sun.intensity = dayFactor * 1.2f;
+            }
+
+            float t = Mathf.Clamp01(Mathf.Cos((_timeOfDay - 0.25f) * Mathf.PI * 2f) * 0.5f + 0.5f);
+            RenderSettings.ambientLight = Color.Lerp(nightAmbient, dayAmbient, t);
+            Camera mainCam = Camera.main;
+            if (mainCam != null)
+            {
+                mainCam.backgroundColor = Color.Lerp(nightSky, daySky, t);
+            }
+
+            UpdateStreetLights(t);
+        }
+
+        private void UpdateStreetLights(float dayFactor)
+        {
+            if (streetLights == null) return;
+            bool on = dayFactor < streetLightThreshold;
+            foreach (var l in streetLights)
+                if (l != null) l.enabled = on;
+        }
+
+        /// <summary>Current time of day in 0..1 range (0=midnight).</summary>
+        public float TimeOfDay => _timeOfDay;
+    }
+}

examples/open_world_city/Assets/Scripts/DayNightCycle.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 06ebd9e278d5fc98279370f9128b86f9
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/GameManager.cs

@@ -0,0 +1,116 @@
+using UnityEngine;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// Bootstrap that wires up the generated systems on scene load. The
+    /// scene only needs an empty GameObject with this component attached.
+    /// </summary>
+    public class GameManager : MonoBehaviour
+    {
+        [Header("Player")]
+        public GameObject playerPrefab;
+        public Vector3 spawnPosition = new Vector3(0f, 2f, 0f);
+
+        [Header("City")]
+        public int cityGridX = 8;
+        public int cityGridZ = 8;
+
+        private void Start()
+        {
+            SpawnPlayer();
+            SpawnCity();
+            SpawnLights();
+            SetupCamera();
+            SetupAudio();
+            SetupUI();
+        }
+
+        private void SpawnPlayer()
+        {
+            GameObject player = playerPrefab != null
+                ? Instantiate(playerPrefab, spawnPosition, Quaternion.identity)
+                : CreatePrimitivePlayer();
+            player.tag = "Player";
+            player.name = "Player";
+
+            var pc = player.GetComponent<PlayerController>();
+            if (pc == null) pc = player.AddComponent<PlayerController>();
+            var rb = player.GetComponent<Rigidbody>();
+            if (rb == null) rb = player.AddComponent<Rigidbody>();
+            var col = player.GetComponent<CapsuleCollider>();
+            if (col == null) col = player.AddComponent<CapsuleCollider>();
+            col.height = 2f; col.radius = 0.4f; col.center = new Vector3(0f, 1f, 0f);
+            rb.constraints = RigidbodyConstraints.FreezeRotation;
+        }
+
+        private GameObject CreatePrimitivePlayer()
+        {
+            GameObject go = GameObject.CreatePrimitive(PrimitiveType.Capsule);
+            go.transform.position = spawnPosition;
+            return go;
+        }
+
+        private void SpawnCity()
+        {
+            GameObject city = new GameObject("City");
+            var gen = city.AddComponent<CityGenerator>();
+            gen.gridX = cityGridX;
+            gen.gridZ = cityGridZ;
+
+            GameObject roads = new GameObject("Roads");
+            roads.transform.SetParent(city.transform, false);
+            var net = roads.AddComponent<RoadNetwork>();
+            net.gridSize = Mathf.Max(cityGridX, cityGridZ);
+        }
+
+        private void SpawnLights()
+        {
+            GameObject sunGo = new GameObject("Sun");
+            var sun = sunGo.AddComponent<Light>();
+            sun.type = LightType.Directional;
+            sun.intensity = 1.2f;
+            sun.shadows = LightShadows.Soft;
+
+            var dnc = sunGo.AddComponent<DayNightCycle>();
+            dnc.sun = sun;
+            // Bind street lights from the city generator after one frame.
+            StartCoroutine(BindStreetLights(dnc));
+        }
+
+        private System.Collections.IEnumerator BindStreetLights(DayNightCycle dnc)
+        {
+            yield return null; // allow CityGenerator.Start() to run
+            var cg = FindObjectOfType<CityGenerator>();
+            if (cg != null) dnc.streetLights = cg.StreetLights;
+        }
+
+        private void SetupCamera()
+        {
+            Camera cam = Camera.main;
+            if (cam == null)
+            {
+                var go = new GameObject("Main Camera");
+                cam = go.AddComponent<Camera>();
+                go.tag = "MainCamera";
+                go.AddComponent<AudioListener>();
+            }
+            var tpc = cam.GetComponent<ThirdPersonCamera>();
+            if (tpc == null) tpc = cam.gameObject.AddComponent<ThirdPersonCamera>();
+            var player = GameObject.FindGameObjectWithTag("Player");
+            tpc.target = player != null ? player.transform : null;
+        }
+
+        private void SetupAudio()
+        {
+            var go = new GameObject("AudioManager");
+            go.AddComponent<AudioManager>();
+        }
+
+        private void SetupUI()
+        {
+            var go = new GameObject("UIManager");
+            go.AddComponent<UIManager>();
+        }
+    }
+}

examples/open_world_city/Assets/Scripts/GameManager.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 146f64a8241e4314114edb414ce6d721
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/HealthSystem.cs

@@ -0,0 +1,82 @@
+using UnityEngine;
+using UnityEngine.Events;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// Damageable entity with health regen and death event. Pairs with the
+    /// optional <see cref="HealthBar"/> UI component.
+    /// </summary>
+    public class HealthSystem : MonoBehaviour
+    {
+        [Header("Health")]
+        public float maxHealth = 100f;
+        public float currentHealth { get; private set; }
+        public float regenPerSecond = 1f;
+        public float regenDelay = 5f;
+
+        [Header("Events")]
+        public UnityEvent onDeath;
+        public UnityEvent<float> onDamaged;
+
+        private float _lastDamageTime;
+        private bool _dead;
+
+        public float Normalised => currentHealth / maxHealth;
+
+        private void Awake()
+        {
+            currentHealth = maxHealth;
+        }
+
+        private void Update()
+        {
+            if (_dead) return;
+            if (Time.time - _lastDamageTime > regenDelay && currentHealth < maxHealth)
+            {
+                currentHealth = Mathf.Min(maxHealth, currentHealth + regenPerSecond * Time.deltaTime);
+            }
+        }
+
+        public void TakeDamage(float amount)
+        {
+            if (_dead) return;
+            currentHealth = Mathf.Max(0f, currentHealth - amount);
+            _lastDamageTime = Time.time;
+            onDamaged?.Invoke(amount);
+            if (currentHealth <= 0f) Die();
+        }
+
+        public void Heal(float amount)
+        {
+            if (_dead) return;
+            currentHealth = Mathf.Min(maxHealth, currentHealth + amount);
+        }
+
+        private void Die()
+        {
+            _dead = true;
+            onDeath?.Invoke();
+            Destroy(gameObject, 0.5f);
+        }
+    }
+
+    /// <summary>
+    /// Simple health bar that reads a <see cref="HealthSystem"/> and updates
+    /// a child <c>Image.fillAmount</c>.
+    /// </summary>
+    public class HealthBar : MonoBehaviour
+    {
+        public HealthSystem source;
+        public UnityEngine.UI.Image fillImage;
+        public bool hideWhenFull = true;
+
+        private void Update()
+        {
+            if (source == null || fillImage == null) return;
+            float n = source.Normalised;
+            fillImage.fillAmount = n;
+            if (hideWhenFull) fillImage.transform.parent.gameObject.SetActive(n < 0.999f);
+        }
+    }
+}

examples/open_world_city/Assets/Scripts/HealthSystem.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 3e2b705888cccf6861f62175541c5a1d
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/NPCController.cs

@@ -0,0 +1,124 @@
+using UnityEngine;
+using UnityEngine.AI;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// AI NPC that wanders between random points and chases the player when
+    /// they enter the aggro radius. Uses Unity's NavMeshAgent.
+    /// </summary>
+    [RequireComponent(typeof(NavMeshAgent))]
+    public class NPCController : MonoBehaviour
+    {
+        public enum State { Idle, Wander, Chase }
+
+        [Header("References")]
+        public Transform player;
+
+        [Header("Behaviour")]
+        public State initialState = State.Wander;
+        public float wanderRadius = 20f;
+        public float aggroRange = 12f;
+        public float loseSightRange = 20f;
+        public float idleDuration = 2f;
+        public float wanderSpeed = 2.5f;
+        public float chaseSpeed = 5f;
+
+        [Header("Debug")]
+        public bool drawGizmos = true;
+
+        private NavMeshAgent _agent;
+        private State _state;
+        private float _stateTimer;
+        private Vector3 _startPos;
+
+        private void Awake()
+        {
+            _agent = GetComponent<NavMeshAgent>();
+            _agent.speed = wanderSpeed;
+        }
+
+        private void Start()
+        {
+            _state = initialState;
+            _startPos = transform.position;
+            if (player == null && GameObject.FindGameObjectWithTag("Player") != null)
+                player = GameObject.FindGameObjectWithTag("Player").transform;
+        }
+
+        private void Update()
+        {
+            switch (_state)
+            {
+                case State.Idle: TickIdle(); break;
+                case State.Wander: TickWander(); break;
+                case State.Chase: TickChase(); break;
+            }
+        }
+
+        private void TickIdle()
+        {
+            _stateTimer -= Time.deltaTime;
+            if (PlayerInRange(aggroRange)) { EnterChase(); return; }
+            if (_stateTimer <= 0f) EnterWander();
+        }
+
+        private void TickWander()
+        {
+            if (PlayerInRange(aggroRange)) { EnterChase(); return; }
+            if (_agent.remainingDistance <= _agent.stoppingDistance && !_agent.pathPending)
+                EnterIdle();
+        }
+
+        private void TickChase()
+        {
+            if (player == null) { EnterWander(); return; }
+            _agent.SetDestination(player.position);
+
+            if (!PlayerInRange(loseSightRange)) EnterWander();
+        }
+
+        private void EnterIdle()
+        {
+            _state = State.Idle;
+            _stateTimer = idleDuration;
+            _agent.isStopped = true;
+        }
+
+        private void EnterWander()
+        {
+            _state = State.Wander;
+            _agent.speed = wanderSpeed;
+            _agent.isStopped = false;
+            Vector3 dir = Random.insideUnitSphere * wanderRadius;
+            dir.y = 0f;
+            Vector3 target = _startPos + dir;
+            if (NavMesh.SamplePosition(target, out NavMeshHit hit, wanderRadius, NavMesh.AllAreas))
+                _agent.SetDestination(hit.position);
+        }
+
+        private void EnterChase()
+        {
+            _state = State.Chase;
+            _agent.speed = chaseSpeed;
+            _agent.isStopped = false;
+        }
+
+        private bool PlayerInRange(float range)
+        {
+            if (player == null) return false;
+            return Vector3.Distance(transform.position, player.position) <= range;
+        }
+
+        private void OnDrawGizmosSelected()
+        {
+            if (!drawGizmos) return;
+            Gizmos.color = Color.yellow;
+            Gizmos.DrawWireSphere(transform.position, aggroRange);
+            Gizmos.color = Color.red;
+            Gizmos.DrawWireSphere(transform.position, loseSightRange);
+            Gizmos.color = Color.green;
+            Gizmos.DrawWireSphere(_startPos == Vector3.zero ? transform.position : _startPos, wanderRadius);
+        }
+    }
+}

examples/open_world_city/Assets/Scripts/NPCController.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: bdb23444532d812096a8a0bf7c0f341f
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/PickupSystem.cs

@@ -0,0 +1,63 @@
+using UnityEngine;
+using UnityEngine.Events;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// Collectible pickup. Triggers an event when collected and adds to the
+    /// global PickupSystem score.
+    /// </summary>
+    [RequireComponent(typeof(Collider))]
+    public class Pickup : MonoBehaviour
+    {
+        public int value = 10;
+        public AudioClip collectClip;
+        public UnityEvent onCollected;
+
+        private void Reset()
+        {
+            GetComponent<Collider>().isTrigger = true;
+        }
+
+        private void OnTriggerEnter(Collider other)
+        {
+            if (!other.CompareTag("Player")) return;
+            PickupSystem.Instance?.Collect(value);
+            onCollected?.Invoke();
+            if (collectClip != null && PickupSystem.Instance != null)
+                PickupSystem.Instance.PlayPickupSound(collectClip);
+            Destroy(gameObject);
+        }
+    }
+
+    /// <summary>
+    /// Singleton that tracks the player's score and plays pickup sounds.
+    /// </summary>
+    public class PickupSystem : MonoBehaviour
+    {
+        public static PickupSystem Instance { get; private set; }
+
+        public int score { get; private set; }
+        public AudioSource audioSource;
+
+        public System.Action<int> onScoreChanged;
+
+        private void Awake()
+        {
+            if (Instance != null && Instance != this) { Destroy(gameObject); return; }
+            Instance = this;
+            if (audioSource == null) audioSource = gameObject.AddComponent<AudioSource>();
+        }
+
+        public void Collect(int amount)
+        {
+            score += amount;
+            onScoreChanged?.Invoke(score);
+        }
+
+        public void PlayPickupSound(AudioClip clip)
+        {
+            if (audioSource != null && clip != null) audioSource.PlayOneShot(clip);
+        }
+    }
+}

examples/open_world_city/Assets/Scripts/PickupSystem.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 08af630d5809345e6854281a491a6740
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/PlayerController.cs

@@ -0,0 +1,109 @@
+using UnityEngine;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// Third-person character controller with WASD movement, jump and a
+    /// rigidbody-based physics response. Designed to be paired with the
+    /// ThirdPersonCamera component.
+    /// </summary>
+    [RequireComponent(typeof(Rigidbody))]
+    [RequireComponent(typeof(CapsuleCollider))]
+    public class PlayerController : MonoBehaviour
+    {
+        [Header("Movement")]
+        public float moveSpeed = 6f;
+        public float sprintMultiplier = 1.6f;
+        public float rotationSmooth = 12f;
+        public float jumpForce = 7.5f;
+
+        [Header("Ground Check")]
+        public float groundCheckDistance = 0.2f;
+        public LayerMask groundMask = ~0;
+
+        [Header("Camera")]
+        public Transform cameraTransform;
+
+        private Rigidbody _rb;
+        private CapsuleCollider _col;
+        private Vector2 _moveInput;
+        private bool _jumpRequested;
+        private bool _isGrounded;
+        private float _targetRotation;
+
+        private void Awake()
+        {
+            _rb = GetComponent<Rigidbody>();
+            _col = GetComponent<CapsuleCollider>();
+            _rb.freezeRotation = true;
+            _rb.interpolation = RigidbodyInterpolation.Interpolate;
+            if (cameraTransform == null && Camera.main != null)
+                cameraTransform = Camera.main.transform;
+        }
+
+        private void Update()
+        {
+            _moveInput.x = Input.GetAxisRaw("Horizontal");
+            _moveInput.y = Input.GetAxisRaw("Vertical");
+            _moveInput = Vector2.ClampMagnitude(_moveInput, 1f);
+
+            if (Input.GetButtonDown("Jump") && _isGrounded)
+                _jumpRequested = true;
+        }
+
+        private void FixedUpdate()
+        {
+            GroundCheck();
+            Move();
+            if (_jumpRequested)
+            {
+                _rb.AddForce(Vector3.up * jumpForce, ForceMode.VelocityChange);
+                _jumpRequested = false;
+            }
+        }
+
+        private void GroundCheck()
+        {
+            Vector3 origin = transform.position + Vector3.up * (_col.height * 0.5f - _col.radius);
+            _isGrounded = Physics.SphereCast(
+                origin, _col.radius * 0.9f, Vector3.down,
+                out _, groundCheckDistance, groundMask, QueryTriggerInteraction.Ignore);
+        }
+
+        private void Move()
+        {
+            float speed = moveSpeed;
+            if (Input.GetKey(KeyCode.LeftShift)) speed *= sprintMultiplier;
+
+            if (_moveInput.sqrMagnitude < 0.01f)
+            {
+                // Apply horizontal damping so the character stops cleanly.
+                Vector3 v = _rb.velocity;
+                v.x *= 0.85f;
+                v.z *= 0.85f;
+                _rb.velocity = v;
+                return;
+            }
+
+            Vector3 camForward = cameraTransform ? cameraTransform.forward : transform.forward;
+            Vector3 camRight = cameraTransform ? cameraTransform.right : transform.right;
+            camForward.y = 0f; camForward.Normalize();
+            camRight.y = 0f; camRight.Normalize();
+
+            Vector3 desired = (camForward * _moveInput.y + camRight * _moveInput.x) * speed;
+            Vector3 velocity = _rb.velocity;
+            velocity.x = desired.x;
+            velocity.z = desired.z;
+            _rb.velocity = velocity;
+
+            if (desired.sqrMagnitude > 0.01f)
+            {
+                _targetRotation = Mathf.Atan2(desired.x, desired.z) * Mathf.Rad2Deg;
+                float smoothed = Mathf.LerpAngle(
+                    transform.rotation.eulerAngles.y, _targetRotation,
+                    Time.fixedDeltaTime * rotationSmooth);
+                _rb.MoveRotation(Quaternion.Euler(0f, smoothed, 0f));
+            }
+        }
+    }
+}

examples/open_world_city/Assets/Scripts/PlayerController.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: c6566cf7b83ff91f376a7d09d43b5fd3
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/RoadNetwork.cs

@@ -0,0 +1,75 @@
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// Lays out a grid road network at runtime: builds thin box meshes for
+    /// roads and an intersection marker at every grid crossing.
+    /// </summary>
+    public class RoadNetwork : MonoBehaviour
+    {
+        [Header("Grid")]
+        public int gridSize = 5;
+        public float blockSpacing = 30f;
+        public float roadWidth = 6f;
+        public float roadThickness = 0.1f;
+
+        [Header("Materials")]
+        public Material roadMaterial;
+        public Material intersectionMaterial;
+
+        private readonly List<GameObject> _roads = new List<GameObject>();
+
+        private void Start()
+        {
+            Build();
+        }
+
+        public void Build()
+        {
+            foreach (var r in _roads) if (r != null) Destroy(r);
+            _roads.Clear();
+
+            float total = (gridSize - 1) * blockSpacing;
+            Vector3 origin = transform.position - new Vector3(total * 0.5f, 0f, total * 0.5f);
+
+            for (int i = 0; i < gridSize; i++)
+            {
+                // Horizontal road
+                _roads.Add(SpawnRoad(
+                    new Vector3(origin.x + total * 0.5f, 0f, origin.z + i * blockSpacing),
+                    new Vector3(total + roadWidth, roadThickness, roadWidth),
+                    roadMaterial, $"Road_H_{i}"));
+
+                // Vertical road
+                _roads.Add(SpawnRoad(
+                    new Vector3(origin.x + i * blockSpacing, 0f, origin.z + total * 0.5f),
+                    new Vector3(roadWidth, roadThickness, total + roadWidth),
+                    roadMaterial, $"Road_V_{i}"));
+            }
+
+            // Intersections.
+            for (int x = 0; x < gridSize; x++)
+            {
+                for (int z = 0; z < gridSize; z++)
+                {
+                    Vector3 p = new Vector3(origin.x + x * blockSpacing, 0f, origin.z + z * blockSpacing);
+                    _roads.Add(SpawnRoad(p, new Vector3(roadWidth * 1.2f, roadThickness * 1.5f, roadWidth * 1.2f),
+                                          intersectionMaterial, $"Intersection_{x}_{z}"));
+                }
+            }
+        }
+
+        private GameObject SpawnRoad(Vector3 pos, Vector3 scale, Material mat, string name)
+        {
+            GameObject go = GameObject.CreatePrimitive(PrimitiveType.Cube);
+            go.name = name;
+            go.transform.SetParent(transform, false);
+            go.transform.position = pos + transform.position;
+            go.transform.localScale = scale;
+            if (mat != null) go.GetComponent<MeshRenderer>().sharedMaterial = mat;
+            return go;
+        }
+    }
+}

examples/open_world_city/Assets/Scripts/RoadNetwork.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 4afc638bbfb2ca81ab494f215750fc85
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/SaveSystem.cs

@@ -0,0 +1,66 @@
+using System;
+using System.IO;
+using UnityEngine;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// JSON save system using <see cref="JsonUtility"/>. Stores a single
+    /// save slot per profile in <c>Application.persistentDataPath</c>.
+    /// </summary>
+    public class SaveSystem : MonoBehaviour
+    {
+        public static SaveSystem Instance { get; private set; }
+
+        public string profileName = "default";
+
+        private void Awake()
+        {
+            if (Instance != null && Instance != this) { Destroy(gameObject); return; }
+            Instance = this;
+            DontDestroyOnLoad(gameObject);
+        }
+
+        private string SavePath => Path.Combine(Application.persistentDataPath, profileName + ".save");
+
+        public void Save<T>(T data) where T : class
+        {
+            try
+            {
+                string json = JsonUtility.ToJson(new Wrapper<T> { payload = data }, true);
+                File.WriteAllText(SavePath, json);
+                Debug.Log($"[SaveSystem] Saved to {SavePath}");
+            }
+            catch (Exception e)
+            {
+                Debug.LogError($"[SaveSystem] Save failed: {e}");
+            }
+        }
+
+        public T Load<T>() where T : class
+        {
+            if (!File.Exists(SavePath)) return null;
+            try
+            {
+                string json = File.ReadAllText(SavePath);
+                var w = JsonUtility.FromJson<Wrapper<T>>(json);
+                return w?.payload;
+            }
+            catch (Exception e)
+            {
+                Debug.LogError($"[SaveSystem] Load failed: {e}");
+                return null;
+            }
+        }
+
+        public bool HasSave => File.Exists(SavePath);
+
+        public void Delete()
+        {
+            if (File.Exists(SavePath)) File.Delete(SavePath);
+        }
+
+        [Serializable]
+        private class Wrapper<T> { public T payload; }
+    }
+}

examples/open_world_city/Assets/Scripts/SaveSystem.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 713fe181501c9d094612732235d78b10
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/ThirdPersonCamera.cs

@@ -0,0 +1,85 @@
+using UnityEngine;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// Smooth third-person camera with collision handling. Attach to a Camera
+    /// GameObject and assign the target transform in the inspector.
+    /// </summary>
+    public class ThirdPersonCamera : MonoBehaviour
+    {
+        [Header("Target")]
+        public Transform target;
+
+        [Header("Positioning")]
+        public Vector3 pivotOffset = new Vector3(0f, 1.5f, 0f);
+        public float distance = 5f;
+        public float minDistance = 1.5f;
+        public float maxDistance = 8f;
+        public float height = 1.2f;
+
+        [Header("Smoothing")]
+        public float positionSmooth = 10f;
+        public float rotationSmooth = 10f;
+
+        [Header("Collision")]
+        public LayerMask collisionMask = ~0;
+        public float collisionRadius = 0.3f;
+
+        [Header("Input")]
+        public bool useMouseOrbit = true;
+        public float mouseSensitivity = 3f;
+        public float minPitch = -30f;
+        public float maxPitch = 75f;
+
+        private float _yaw;
+        private float _pitch = 15f;
+        private float _currentDistance;
+
+        private void Start()
+        {
+            _currentDistance = distance;
+            if (target != null)
+            {
+                Vector3 e = transform.eulerAngles;
+                _yaw = e.y; _pitch = e.x;
+            }
+            Cursor.lockState = CursorLockMode.Locked;
+        }
+
+        private void LateUpdate()
+        {
+            if (target == null) return;
+
+            if (useMouseOrbit)
+            {
+                _yaw += Input.GetAxis("Mouse X") * mouseSensitivity;
+                _pitch -= Input.GetAxis("Mouse Y") * mouseSensitivity;
+                _pitch = Mathf.Clamp(_pitch, minPitch, maxPitch);
+            }
+
+            Quaternion rotation = Quaternion.Euler(_pitch, _yaw, 0f);
+            Vector3 pivot = target.position + pivotOffset;
+
+            // Desired camera position.
+            Vector3 desired = pivot + rotation * new Vector3(0f, height, -distance);
+
+            // Collision: shrink the distance if there's an obstacle.
+            if (Physics.SphereCast(
+                pivot, collisionRadius, (desired - pivot).normalized,
+                out RaycastHit hit, distance, collisionMask, QueryTriggerInteraction.Ignore))
+            {
+                _currentDistance = Mathf.Clamp(hit.distance, minDistance, distance);
+            }
+            else
+            {
+                _currentDistance = Mathf.Lerp(_currentDistance, distance, Time.deltaTime * 4f);
+            }
+
+            Vector3 finalPos = pivot + rotation * new Vector3(0f, height, -_currentDistance);
+            transform.position = Vector3.Lerp(transform.position, finalPos, positionSmooth * Time.deltaTime);
+            transform.rotation = Quaternion.Slerp(
+                transform.rotation, rotation, rotationSmooth * Time.deltaTime);
+        }
+    }
+}

examples/open_world_city/Assets/Scripts/ThirdPersonCamera.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: d76bc6d6a55fca62d80d72f6cff57325
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/UIManager.cs

@@ -0,0 +1,59 @@
+using UnityEngine;
+using UnityEngine.UI;
+using TMPro;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// Lightweight HUD manager using Unity UI + TextMeshPro. Exposes methods
+    /// for other systems to update score / health / messages.
+    /// </summary>
+    public class UIManager : MonoBehaviour
+    {
+        public static UIManager Instance { get; private set; }
+
+        [Header("HUD")]
+        public TMP_Text scoreText;
+        public TMP_Text healthText;
+        public TMP_Text messageText;
+        public Image healthBarFill;
+
+        [Header("Message")]
+        public float messageDuration = 2f;
+
+        private float _messageTimer;
+
+        private void Awake()
+        {
+            if (Instance != null && Instance != this) { Destroy(gameObject); return; }
+            Instance = this;
+            SetMessage(string.Empty);
+        }
+
+        private void Update()
+        {
+            if (_messageTimer > 0f)
+            {
+                _messageTimer -= Time.deltaTime;
+                if (_messageTimer <= 0f && messageText != null) messageText.text = string.Empty;
+            }
+        }
+
+        public void SetScore(int score)
+        {
+            if (scoreText != null) scoreText.text = $"Score: {score}";
+        }
+
+        public void SetHealth(float current, float max)
+        {
+            if (healthText != null) healthText.text = $"HP: {Mathf.CeilToInt(current)} / {Mathf.CeilToInt(max)}";
+            if (healthBarFill != null) healthBarFill.fillAmount = Mathf.Clamp01(current / max);
+        }
+
+        public void SetMessage(string msg)
+        {
+            if (messageText != null) messageText.text = msg;
+            _messageTimer = string.IsNullOrEmpty(msg) ? 0f : messageDuration;
+        }
+    }
+}

examples/open_world_city/Assets/Scripts/UIManager.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: dcbdcd3761369cee5079e3e57f514884
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/UnityAgent.Scripts.asmdef

@@ -0,0 +1,11 @@
+{
+  "name": "UnityAgent.Scripts",
+  "rootNamespace": "UnityAgent",
+  "references": [],
+  "includePlatforms": [],
+  "excludePlatforms": [],
+  "allowUnsafeCode": false,
+  "autoReferenced": true,
+  "defineConstraints": [],
+  "versionDefines": []
+}

examples/open_world_city/Assets/Scripts/UnityAgent.Scripts.asmdef.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 51397beb9916b964e08c142ac4dd2500
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Assets/Scripts/VehicleController.cs

@@ -0,0 +1,136 @@
+using UnityEngine;
+
+namespace UnityAgent
+{
+    /// <summary>
+    /// Arcade car physics: motor torque, steering, braking and a simple
+    /// four-wheel raycast suspension. Place this on a root GameObject with
+    /// a Rigidbody and four wheel transforms.
+    /// </summary>
+    [RequireComponent(typeof(Rigidbody))]
+    public class VehicleController : MonoBehaviour
+    {
+        [System.Serializable]
+        public class Wheel
+        {
+            public Transform transform;
+            public bool isSteering;
+            public bool isPowered;
+            public bool isBraking;
+            [HideInInspector] public bool isGrounded;
+            [HideInInspector] public float suspensionOffset;
+        }
+
+        [Header("Wheels")]
+        public Wheel[] wheels = new Wheel[4];
+
+        [Header("Engine")]
+        public float motorTorque = 1500f;
+        public float brakeTorque = 3000f;
+        public float maxSteerAngle = 30f;
+        public float maxSpeedKph = 180f;
+
+        [Header("Suspension")]
+        public float suspensionRestLength = 0.5f;
+        public float suspensionSpring = 35000f;
+        public float suspensionDamper = 4500f;
+        public float wheelRadius = 0.35f;
+        public LayerMask wheelMask = ~0;
+
+        [Header("Aerodynamics")]
+        public float downforce = 100f;
+        public float centerOfMassOffset = -0.5f;
+
+        private Rigidbody _rb;
+        private float _throttle;
+        private float _steer;
+        private float _brake;
+
+        private void Awake()
+        {
+            _rb = GetComponent<Rigidbody>();
+            _rb.centerOfMass += Vector3.up * centerOfMassOffset;
+            _rb.interpolation = RigidbodyInterpolation.Interpolate;
+        }
+
+        private void Update()
+        {
+            _throttle = Input.GetAxis("Vertical");
+            _steer = Input.GetAxis("Horizontal");
+            _brake = Input.GetKey(KeyCode.Space) ? 1f : 0f;
+        }
+
+        private void FixedUpdate()
+        {
+            UpdateWheels();
+            ApplySuspension();
+            ApplyDrive();
+            ApplyDownforce();
+        }
+
+        private void UpdateWheels()
+        {
+            foreach (var w in wheels)
+            {
+                if (w.transform == null) continue;
+                Vector3 origin = w.transform.position;
+                bool hit = Physics.Raycast(
+                    origin, -transform.up, out RaycastHit r,
+                    suspensionRestLength + wheelRadius, wheelMask,
+                    QueryTriggerInteraction.Ignore);
+                w.isGrounded = hit;
+                w.suspensionOffset = hit ? r.distance - wheelRadius : suspensionRestLength;
+            }
+        }
+
+        private void ApplySuspension()
+        {
+            foreach (var w in wheels)
+            {
+                if (!w.isGrounded) continue;
+                float force = (suspensionRestLength - w.suspensionOffset) * suspensionSpring;
+                Vector3 velocity = _rb.GetPointVelocity(w.transform.position);
+                float upwardVel = Vector3.Dot(transform.up, velocity);
+                force -= upwardVel * suspensionDamper;
+                _rb.AddForceAtPosition(transform.up * Mathf.Max(0f, force), w.transform.position);
+            }
+        }
+
+        private void ApplyDrive()
+        {
+            float kph = _rb.velocity.magnitude * 3.6f;
+            float speedFactor = Mathf.Clamp01(1f - kph / maxSpeedKph);
+
+            foreach (var w in wheels)
+            {
+                if (!w.isGrounded) continue;
+                if (w.isPowered)
+                {
+                    Vector3 force = transform.forward * (_throttle * motorTorque * speedFactor);
+                    _rb.AddForceAtPosition(force, w.transform.position, ForceMode.Force);
+                }
+                if (w.isBraking && _brake > 0.01f)
+                {
+                    Vector3 brakeForce = -transform.forward * (_brake * brakeTorque);
+                    _rb.AddForceAtPosition(brakeForce, w.transform.position, ForceMode.Force);
+                }
+                if (w.isSteering)
+                {
+                    // Rotate the visual wheel and apply a small yaw torque.
+                    w.transform.localRotation = Quaternion.Euler(0f, _steer * maxSteerAngle, 0f);
+                }
+            }
+            // Steering yaw torque.
+            if (Mathf.Abs(_steer) > 0.01f)
+            {
+                float turn = _steer * maxSteerAngle * 0.02f;
+                _rb.AddTorque(transform.up * turn * (_rb.velocity.magnitude + 1f), ForceMode.Force);
+            }
+        }
+
+        private void ApplyDownforce()
+        {
+            _rb.AddForce(-transform.up * downforce * _rb.velocity.magnitude);
+        }
+    }
+}

examples/open_world_city/Assets/Scripts/VehicleController.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 67179e275140460130f6cafb48739957
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

examples/open_world_city/Packages/manifest.json

@@ -0,0 +1,23 @@
+{
+  "dependencies": {
+    "com.unity.ai.navigation": "1.1.5",
+    "com.unity.cinemachine": "2.9.7",
+    "com.unity.collab-proxy": "2.2.0",
+    "com.unity.ide.rider": "3.0.27",
+    "com.unity.ide.visualstudio": "2.0.22",
+    "com.unity.inputsystem": "1.7.0",
+    "com.unity.postprocessing": "3.4.0",
+    "com.unity.textmeshpro": "3.0.6",
+    "com.unity.ugui": "1.0.0",
+    "com.unity.modules.ai": "1.0.0",
+    "com.unity.modules.animation": "1.0.0",
+    "com.unity.modules.audio": "1.0.0",
+    "com.unity.modules.imageconversion": "1.0.0",
+    "com.unity.modules.particlesystem": "1.0.0",
+    "com.unity.modules.physics": "1.0.0",
+    "com.unity.modules.physics2d": "1.0.0",
+    "com.unity.modules.terrain": "1.0.0",
+    "com.unity.modules.terrainphysics": "1.0.0",
+    "com.unity.modules.ui": "1.0.0"
+  }
+}

examples/open_world_city/ProjectSettings/ProjectSettings.asset

@@ -0,0 +1,10 @@
+%YAML 1.1
+%TAG !u! tag:unity3d.com,2011:
+--- !u!129 &1
+PlayerSettings:
+  m_ObjectHideFlags: 0
+  serializedVersion: 26
+  companyName: UnityAgent
+  productName: open_world_city
+  defaultCursor: {instanceID: 0}
+  m_Version: 1

examples/open_world_city/ProjectSettings/ProjectVersion.txt

@@ -0,0 +1 @@
+m_EditorVersion: 2022.3.20f1

examples/open_world_city/ProjectSettings/TagManager.asset

@@ -0,0 +1,15 @@
+%YAML 1.1
+%TAG !u! tag:unity3d.com,2011:
+--- !u!78 &1
+TagManager:
+  serializedVersion: 2
+  tags:
+  - Player
+  - Enemy
+  - Pickup
+  layers:
+  - Default
+  - TransparentFX
+  - Ignore Raycast
+  - Water
+  - UI

pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unity-agent"
+version = "0.1.0"
+description = "A Python agent that generates complete Unity game projects (C#, .unity scenes, project config) you can open and play in any Unity 2022+ installation."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Unity Agent" }]
+keywords = ["unity", "unity3d", "game-development", "code-generation", "agent"]
+
+[project.scripts]
+unity-agent = "unity_agent.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["unity_agent*"]
+
+[tool.setuptools.package-data]
+"unity_agent.knowledge" = ["entries/*.md", "README.md"]

unity_agent/__init__.py

@@ -0,0 +1,32 @@
+"""
+Unity Agent - A Python package that generates complete Unity game projects.
+
+The agent uses a collection of code-generation tools to emit compilable C#
+scripts, Unity scene (.unity) files, project configuration (.meta, ProjectSettings,
+Packages/manifest.json) and an open-world example game.
+
+Quick start
+-----------
+>>> from unity_agent.config import Settings
+>>> from unity_agent.transport.unity_transport import UnityTransport
+>>> from unity_agent.tools.unity_tools import GenerateCompleteGameTool
+>>> settings = Settings(output_dir="my_game")
+>>> transport = UnityTransport(settings)
+>>> GenerateCompleteGameTool(settings, transport).run(game_name="OpenWorldCity")
+"""
+
+from unity_agent.config import Settings
+from unity_agent.transport.unity_transport import UnityTransport
+from unity_agent.tools.base import ToolBase, ToolRegistry
+from unity_agent.orchestrator.prompts import SYSTEM_PROMPT, build_user_prompt
+
+__all__ = [
+    "Settings",
+    "UnityTransport",
+    "ToolBase",
+    "ToolRegistry",
+    "SYSTEM_PROMPT",
+    "build_user_prompt",
+]
+
+__version__ = "0.1.0"

unity_agent/__main__.py

@@ -0,0 +1,103 @@
+"""Command-line entry point for the unity_agent package.
+
+Usage::
+
+    python -m unity_agent generate --game OpenWorldCity --preset open_world_city
+    python -m unity_agent list-tools
+    python -m unity_agent qa examples/open_world_city
+
+Run ``python -m unity_agent --help`` for the full list of commands.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from unity_agent.config import Settings
+from unity_agent.transport.unity_transport import UnityTransport
+from unity_agent.tools.base import get_registry
+from unity_agent.tools.unity_tools import GenerateCompleteGameTool, SetupUnityProjectTool
+
+
+def _cmd_list_tools(args: argparse.Namespace) -> int:
+    registry = get_registry()
+    for name in registry.all_names():
+        cls = registry.get(name)
+        print(f"  {name:35s} {cls.description}")
+    return 0
+
+
+def _cmd_generate(args: argparse.Namespace) -> int:
+    settings = Settings(
+        output_dir=args.output_dir,
+        product_name=args.game,
+    )
+    transport = UnityTransport(settings)
+    tool = GenerateCompleteGameTool(settings, transport)
+    result = tool.run(game_name=args.game, preset=args.preset, project_name=args.game)
+    print(result.summary)
+    for f in result.files:
+        print(f"  {f}")
+    print()
+    print(transport.summary())
+    return 0 if result.ok else 1
+
+
+def _cmd_setup(args: argparse.Namespace) -> int:
+    settings = Settings(output_dir=args.output_dir, product_name=args.project_name)
+    transport = UnityTransport(settings)
+    tool = SetupUnityProjectTool(settings, transport)
+    result = tool.run(project_name=args.project_name)
+    print(result.summary)
+    for f in result.files:
+        print(f"  {f}")
+    return 0 if result.ok else 1
+
+
+def _cmd_qa(args: argparse.Namespace) -> int:
+    from unity_agent.qa import ProjectQA
+    qa = ProjectQA(args.project_root)
+    report = qa.run()
+    print(report.summary())
+    for issue in report.issues:
+        print(f"  [{issue.severity.upper():7}] {issue.category:8} {issue.message}  {issue.path}")
+    return 0 if report.passed else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="unity_agent", description="Unity game agent CLI.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    p_list = sub.add_parser("list-tools", help="List every registered tool.")
+    p_list.set_defaults(func=_cmd_list_tools)
+
+    p_gen = sub.add_parser("generate", help="Generate a complete game.")
+    p_gen.add_argument("--game", default="OpenWorldCity", help="Game / project name.")
+    p_gen.add_argument("--preset", default="open_world_city",
+                       choices=["open_world_city", "fps_arena", "minimal"])
+    p_gen.add_argument("--output-dir", default="unity_output",
+                       help="Where to write the project (default: unity_output).")
+    p_gen.set_defaults(func=_cmd_generate)
+
+    p_setup = sub.add_parser("setup", help="Scaffold an empty Unity project.")
+    p_setup.add_argument("--project-name", default="GeneratedGame")
+    p_setup.add_argument("--output-dir", default="unity_output")
+    p_setup.set_defaults(func=_cmd_setup)
+
+    p_qa = sub.add_parser("qa", help="Run QA checks on a generated project.")
+    p_qa.add_argument("project_root", help="Path to the project root.")
+    p_qa.set_defaults(func=_cmd_qa)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

unity_agent/config.py

@@ -0,0 +1,90 @@
+"""Global configuration for the Unity agent.
+
+The :class:`Settings` dataclass is the single source of truth for runtime
+parameters such as the Unity installation path, optional LLM API keys, the
+default output directory and project metadata used when scaffolding a new
+Unity project.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Optional
+
+
+DEFAULT_OUTPUT_DIR = "unity_output"
+DEFAULT_UNITY_VERSION = "2022.3.20f1"
+
+# Default Unity project metadata. These values are written into
+# ProjectSettings/ProjectSettings.asset so the editor knows what to display
+# in the project wizard and on the splash screen.
+DEFAULT_COMPANY_NAME = "UnityAgent"
+DEFAULT_PRODUCT_NAME = "GeneratedGame"
+
+
+@dataclass
+class Settings:
+    """Runtime configuration shared by every tool.
+
+    Parameters
+    ----------
+    unity_path:
+        Optional path to the Unity executable (``Unity.exe`` / ``Unity``).
+        When provided, the agent can optionally invoke Unity in batch mode
+        to validate that generated projects compile.
+    unity_version:
+        Target Unity version written into ``ProjectSettings.asset``.
+    output_dir:
+        Root directory where generated projects are written. Can be either a
+        relative path (resolved against the current working directory) or an
+        absolute path.
+    company_name / product_name:
+        Metadata written into the project settings.
+    openai_api_key / anthropic_api_key / zai_api_key:
+        Optional LLM provider keys. Only required if the orchestrator is
+        wired up to call an LLM directly.
+    overwrite:
+        If ``True`` existing files are replaced; otherwise a ``FileExistsError``
+        is raised when a destination file already exists.
+    """
+
+    unity_path: Optional[str] = None
+    unity_version: str = DEFAULT_UNITY_VERSION
+    output_dir: str = DEFAULT_OUTPUT_DIR
+    company_name: str = DEFAULT_COMPANY_NAME
+    product_name: str = DEFAULT_PRODUCT_NAME
+
+    openai_api_key: Optional[str] = field(default_factory=lambda: os.environ.get("OPENAI_API_KEY"))
+    anthropic_api_key: Optional[str] = field(default_factory=lambda: os.environ.get("ANTHROPIC_API_KEY"))
+    zai_api_key: Optional[str] = field(default_factory=lambda: os.environ.get("ZAI_API_KEY"))
+
+    overwrite: bool = True
+    auto_create_dirs: bool = True
+
+    # ------------------------------------------------------------------ #
+    # Convenience helpers
+    # ------------------------------------------------------------------ #
+    @property
+    def output_path(self) -> Path:
+        p = Path(self.output_dir)
+        return p if p.is_absolute() else (Path.cwd() / p)
+
+    def project_path(self, project_name: str) -> Path:
+        """Return the absolute path to a named project inside ``output_dir``."""
+        return self.output_path / project_name
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        """Build a :class:`Settings` instance populated from environment vars."""
+        return cls(
+            unity_path=os.environ.get("UNITY_PATH"),
+            unity_version=os.environ.get("UNITY_VERSION", DEFAULT_UNITY_VERSION),
+            output_dir=os.environ.get("UNITY_AGENT_OUTPUT_DIR", DEFAULT_OUTPUT_DIR),
+            company_name=os.environ.get("UNITY_COMPANY_NAME", DEFAULT_COMPANY_NAME),
+            product_name=os.environ.get("UNITY_PRODUCT_NAME", DEFAULT_PRODUCT_NAME),
+        )

unity_agent/knowledge/README.md

@@ -0,0 +1,33 @@
+# Unity Agent Knowledge Base
+
+This directory contains markdown knowledge entries the agent consults when
+generating Unity projects. Each file is a short, focused reference on one
+area of Unity development.
+
+## Entries
+
+| File                       | Topic                                                      |
+|----------------------------|------------------------------------------------------------|
+| `unity_fundamentals.md`    | MonoBehaviour lifecycle, GameObjects, components, coroutines |
+| `unity_physics.md`         | Rigidbody, colliders, raycasting, physics vs frame step   |
+| `unity_rendering.md`       | Materials, shaders, lighting, post-processing, LOD, fog    |
+| `unity_navigation.md`      | NavMesh, NavMeshAgent, AI state machines, obstacles        |
+| `unity_input_system.md`    | Legacy Input Manager, mouse-look, the new Input System     |
+| `unity_ui.md`              | Canvas, HUD, health bars, TextMeshPro, layout              |
+| `unity_audio.md`           | AudioSource, 3D audio, AudioMixer, AudioManager pattern    |
+| `open_world_design.md`     | Procedural generation, LOD, streaming, day/night, save     |
+
+## How the agent uses these
+
+The orchestrator can embed the contents of these files as context for the
+LLM. The system prompt instructs the LLM to "consult the knowledge entries
+for [topic] when generating code that touches [topic]."
+
+For example, when generating a third-person controller the LLM should pull
+`unity_fundamentals.md` (for the lifecycle) and `unity_input_system.md`
+(for the mouse-look recipe).
+
+## Adding entries
+
+Create a new `.md` file in this directory and update the table above. The
+file name (without `.md`) becomes the entry's slug.

unity_agent/knowledge/__init__.py

@@ -0,0 +1,41 @@
+"""Knowledge base loader.
+
+Provides a simple API for loading the markdown knowledge entries that ship
+with the package. Entries are stored as ``.md`` files in
+``unity_agent/knowledge/entries/``.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+from typing import Dict, List, Optional
+
+
+def entries_dir() -> Path:
+    """Return the absolute path to the knowledge entries directory."""
+    return Path(__file__).resolve().parent / "entries"
+
+
+def list_entries() -> List[str]:
+    """Return a list of knowledge entry slugs (file names without .md)."""
+    d = entries_dir()
+    if not d.exists():
+        return []
+    return sorted(p.stem for p in d.glob("*.md"))
+
+
+def load_entry(slug: str) -> Optional[str]:
+    """Return the markdown body of a knowledge entry, or None if missing."""
+    p = entries_dir() / f"{slug}.md"
+    if not p.exists():
+        return None
+    return p.read_text(encoding="utf-8")
+
+
+def load_all() -> Dict[str, str]:
+    """Return a dict mapping slug -> markdown body for every entry."""
+    return {slug: load_entry(slug) for slug in list_entries()}
+
+
+__all__ = ["entries_dir", "list_entries", "load_entry", "load_all"]

unity_agent/knowledge/entries/open_world_design.md

@@ -0,0 +1,185 @@
+# Open-World Game Design
+
+Designing an open world is fundamentally a trade-off between **density of
+content** and **memory/CPU budget**. This document collects the patterns the
+agent uses when generating the open-world city example.
+
+## Procedural generation
+
+### Grid + jitter
+
+The simplest viable city layout is a grid of blocks where each block holds
+one or more buildings whose position is jittered slightly to break the
+symmetry:
+
+```csharp
+for (int x = 0; x < gridX; x++)
+for (int z = 0; z < gridZ; z++)
+{
+    Vector3 block = origin + new Vector3(x * blockSpacing, 0f, z * blockSpacing);
+    SpawnBuilding(block + Random.insideUnitSphere * 4f);
+}
+```
+
+The generated `CityGenerator.cs` follows this pattern. For more variety,
+swap the grid for:
+
+* **Voronoi street networks** (Delaunay triangulation, then prune).
+* **L-system road growth** (recursive rewrite rules -- great for organic
+  cities).
+* **Wave function collapse** -- tile-based, but expensive to author.
+
+### Building composition
+
+A building is rarely a single mesh. The generated `BuildingGenerator.cs`
+composes three primitives:
+
+1. A wall cube with a Standard material (concrete/glass color).
+2. A slightly smaller cube with an emissive **window material** so windows
+   glow at night.
+3. A `BoxCollider` for collision.
+
+For more variety:
+
+* Vary the footprint (square vs rectangular).
+* Add a flat roof cap with a different material.
+* Add a parapet along the top.
+* Randomly choose between glass-tower, brick-mid-rise, and concrete-low-rise
+  palettes.
+
+### Runtime vs baked
+
+The agent generates everything **at runtime in `Start()`** because:
+
+* The Unity project opens with an empty scene and the user immediately
+  sees content after pressing Play.
+* No need to ship `.unity` scenes with hundreds of GameObjects.
+* Easy to randomize: just change the seed.
+
+The downside is the first-frame hitch on large worlds. Mitigations:
+
+* Spread generation across frames using a coroutine that yields after
+  every N buildings.
+* Use `Object.Instantiate` from a small set of prefabs instead of building
+  primitives from scratch each time.
+* Use `Graphics.DrawMeshInstanced` for buildings once you do not need
+  per-building colliders.
+
+## Level of Detail (LOD)
+
+For an open world you must use LOD. Without it, the GPU processes every
+window pane on every building no matter how far away it is.
+
+| LOD | Screen size | Poly count                  |
+|-----|-------------|-----------------------------|
+| 0   | 60%+        | Full mesh with windows      |
+| 1   | 25-60%      | Simplified mesh, no windows |
+| 2   | 5-25%       | Single box per building     |
+| Culled | <5%      | Not rendered at all         |
+
+Add a `LODGroup` to each building and assign LOD meshes. For procedural
+buildings you can build the LOD meshes in code by reducing the window
+count and merging meshes.
+
+## Streaming and chunking
+
+For worlds larger than ~1km x 1km you must chunk:
+
+* Divide the world into a grid of chunks (e.g. 200m x 200m).
+* Load chunks near the player; unload chunks far away.
+* Use `Addressables` or `SceneManager.LoadSceneAsync(sceneName, LoadSceneMode.Additive)`
+  to load chunk scenes.
+
+The generated example does NOT chunk -- it builds everything in one shot,
+which is fine for an 8x8 block city. Chunking becomes mandatory around
+16x16 blocks.
+
+## Fog and far plane
+
+Always set `RenderSettings.fog` for open worlds. It hides:
+
+* Distant popping when LOD changes happen.
+* The far clip plane edge.
+
+A linear fog from 100m to 800m is a good default for a city.
+
+## Day/Night cycle
+
+The generated `DayNightCycle.cs` rotates a directional light around the X
+axis to simulate the sun:
+
+```csharp
+float sunAngle = (_timeOfDay - 0.25f) * 360f; // 0.25 = noon
+sun.transform.rotation = Quaternion.Euler(sunAngle, -30f, 0f);
+```
+
+* Keep the day length short (60-180 s) for demo purposes; 24 min real time
+  per day for actual gameplay.
+* Lerp ambient light and skybox color between day/night presets so the
+  world does not suddenly flip black.
+* Turn street lights on/off based on a sun-intensity threshold.
+
+## Player traversal
+
+Open worlds need fast traversal. Options:
+
+| Method                | Speed (m/s) | Use case                              |
+|-----------------------|-------------|---------------------------------------|
+| Walking               | 3-5         | On-foot exploration                   |
+| Sprinting             | 7-10        | Short bursts                          |
+| Car (arcade)          | 15-30       | The generated `VehicleController.cs`  |
+| Horse / mount         | 8-12        | Fantasy open world                    |
+| Fast travel           | instant     | Pre-unlocked locations                |
+
+The generated project ships both a `PlayerController` (on-foot) and a
+`VehicleController` (car) so the user can switch between them.
+
+## NPC traffic
+
+For an open-world city, AI traffic should be **lightweight**:
+
+* Use `NavMeshAgent` with a low `acceleration` for cars so they look
+  smooth, not jerky.
+* Pool the agents -- never `Instantiate` a new car every time one drives
+  off-screen.
+* Despawn agents when they are > 100m from the player.
+
+The generated `NPCController.cs` covers pedestrians; for cars you would
+extend it with lane-following logic.
+
+## Save systems
+
+Open worlds need persistent saves. The generated `SaveSystem.cs` writes a
+single JSON file to `Application.persistentDataPath`:
+
+```csharp
+[Serializable]
+public class GameSave
+{
+    public Vector3 playerPosition;
+    public int score;
+    public float timeOfDay;
+    public List<string> completedQuests;
+}
+```
+
+For larger worlds, split saves into:
+
+* Player profile (small, frequent).
+* World state (large, infrequent -- chunk ownership, building destruction,
+  NPC schedules).
+
+## Common pitfalls
+
+* **Floating point precision:** Unity uses single-precision floats. Beyond
+  ~5km from the origin, physics and rendering jitter. Use a **floating
+  origin** that re-centres the world on the player every few hundred metres.
+* **Shadow distance:** the default 150m shadow distance is too short for an
+  open world. Raise to 300-500m for desktop; lower for mobile.
+* **Lighting rebuild:** make sure all your static city geometry is marked
+  **Navigation Static** AND **Lightmap Static** before baking. For runtime-
+  generated cities you cannot bake -- rely on realtime lighting and the
+  directional sun.
+* **Collider spam:** 50 buildings x 6 faces each = 300 colliders. Mark
+  small decoration meshes as `isTrigger = false` and use a single
+  `BoxCollider` per building.

unity_agent/knowledge/entries/unity_audio.md

@@ -0,0 +1,120 @@
+# Unity Audio
+
+Unity plays audio through `AudioSource` components that reference an
+`AudioClip` asset. A single `AudioListener` in the scene is required
+(usually on the Main Camera).
+
+## AudioClip
+
+An `AudioClip` is the audio data. Supported formats: WAV (uncompressed,
+fastest), MP3/Ogg Vorbis (compressed, smaller). Unity imports them and
+lets you choose compression per-platform in the import settings.
+
+## AudioSource
+
+```csharp
+var src = gameObject.AddComponent<AudioSource>();
+src.clip = jumpClip;
+src.volume = 0.7f;
+src.pitch = 1.0f;
+src.loop = false;
+src.playOnAwake = false;
+src.spatialBlend = 0.0f; // 0=2D, 1=3D
+src.Play();
+```
+
+Important properties:
+
+| Property        | Meaning                                                   |
+|-----------------|-----------------------------------------------------------|
+| `clip`          | The AudioClip to play                                     |
+| `volume`        | 0..1                                                      |
+| `pitch`         | Default 1; >1 = higher pitch, <1 = lower                  |
+| `loop`          | Repeat when the clip ends                                 |
+| `playOnAwake`   | Play automatically when the AudioSource is enabled        |
+| `spatialBlend`  | 0=fully 2D, 1=fully 3D (position-based)                   |
+| `minDistance`   | Within this distance the sound is at full volume (3D)     |
+| `maxDistance`   | Beyond this distance the sound is inaudible (3D)          |
+| `rolloffMode`   | Logarithmic, Linear, or custom curve (3D falloff)         |
+
+## 3D audio
+
+For positional sounds (footsteps, gunfire, engines), set
+`spatialBlend = 1.0f`. The volume then depends on the distance between the
+AudioSource and the AudioListener.
+
+```csharp
+src.spatialBlend = 1.0f;
+src.rolloffMode = AudioRolloffMode.Logarithmic;
+src.minDistance = 1f;
+src.maxDistance = 50f;
+```
+
+> Default `maxDistance` is 500 -- way too large for most gameplay. Lower
+> it to 30-50 for SFX.
+
+## One-shot SFX
+
+For short sound effects (pickups, gunshots, impacts) use `PlayOneShot`:
+
+```csharp
+audioSource.PlayOneShot(clip, volumeScale);
+```
+
+`PlayOneShot` can layer multiple clips on the same AudioSource without
+cutting each other off.
+
+## AudioMixer
+
+For volume control and grouping, create an **AudioMixer** asset
+(`Assets > Create > Audio Mixer`). Expose parameters and control them at
+runtime:
+
+```csharp
+[SerializeField] private AudioMixer mixer;
+
+public void SetMasterVolume(float dB) => mixer.SetFloat("MasterVolume", dB);
+public void SetMusicVolume(float dB)  => mixer.SetFloat("MusicVolume", dB);
+public void SetSfxVolume(float dB)    => mixer.SetFloat("SfxVolume", dB);
+```
+
+Convert linear 0..1 to dB:
+
+```csharp
+public static float LinearToDB(float linear) =>
+    linear <= 0.0001f ? -80f : Mathf.Log10(linear) * 20f;
+```
+
+## The AudioManager pattern
+
+The generated `AudioManager.cs` is a singleton with two channels
+(`sfxSource`, `musicSource`). It exposes:
+
+```csharp
+AudioManager.Instance.PlaySfx(pickupClip, 1.0f);
+AudioManager.Instance.PlayMusic(menuMusic);
+AudioManager.Instance.StopMusic();
+AudioManager.Instance.ApplyVolumes();
+```
+
+`DontDestroyOnLoad` keeps the manager alive across scene loads so music
+does not restart.
+
+## AudioListener
+
+* Exactly one `AudioListener` per scene. The Main Camera has one by
+  default; remove it if you add another.
+* The listener's transform defines "where the player's ears are" for 3D
+  audio panning.
+
+## Performance
+
+* Pool AudioSources for sounds that play many times per second (machine
+  guns, rain). Reusing one AudioSource and calling `PlayOneShot` is fine
+  up to ~20 simultaneous clips.
+* Use compressed formats (Vorbis) for music; uncompressed (WAV) for
+  frequent short SFX.
+* Set `AudioClip.preloadAudioData = true` for short clips and `false` for
+  music that should stream from disk.
+* Lower `maxDistance` aggressively; large falloff radii cost CPU on 3D
+  sounds.

unity_agent/knowledge/entries/unity_fundamentals.md

@@ -0,0 +1,99 @@
+# Unity Fundamentals
+
+## MonoBehaviour Lifecycle
+
+Every gameplay script in Unity derives from `MonoBehaviour`. The engine calls
+a fixed sequence of messages; understanding the order is the difference
+between code that runs smoothly and code that stutters or races.
+
+```
+Awake()        -> OnEnable() -> Start()
+                                |
+                                v
+FixedUpdate()  (physics, fixed timestep) --+
+                                           |
+Update()        (input, gameplay)        --+
+                                           |
+LateUpdate()    (camera follow, post-sim) --+
+                                           |
+OnDisable() -> OnDestroy()
+```
+
+| Message        | When it runs                                  | Typical use                                   |
+|----------------|-----------------------------------------------|-----------------------------------------------|
+| `Awake`        | Once, when the script instance is loaded      | Cache components, set up singletons           |
+| `OnEnable`     | Every time the component is enabled           | Subscribe to events                           |
+| `Start`        | Once, before the first Update                 | Cross-object references (other objects' Awake have run) |
+| `FixedUpdate`  | Fixed timestep (default 0.02 s = 50 Hz)       | Rigidbody physics forces                      |
+| `Update`       | Every rendered frame                          | Input polling, gameplay logic                 |
+| `LateUpdate`   | After all Update calls have finished          | Camera follow, post-processing                |
+| `OnDisable`    | When the component is disabled                | Unsubscribe from events                       |
+| `OnDestroy`    | When the GameObject is destroyed              | Cleanup native resources                      |
+
+> **Gotcha:** `Camera.main` searches the scene by tag every call in 2022.3.
+> Cache it in `Awake` if you call it more than once per frame.
+
+## GameObjects and Components
+
+A `GameObject` is an empty container. Behaviour is added through
+**components**:
+
+```csharp
+var go = new GameObject("Enemy");
+go.transform.position = Vector3.zero;
+go.AddComponent<Rigidbody>();
+go.AddComponent<CapsuleCollider>();
+var ai = go.AddComponent<NPCController>();
+ai.player = GameObject.FindGameObjectWithTag("Player").transform;
+```
+
+* Every GameObject always has a `Transform` (or `RectTransform` under a
+  Canvas). You cannot remove it.
+* Use `GetComponent<T>()` / `GetComponentInChildren<T>()` /
+  `GetComponentInParent<T>()` to reach related components. Cache the result
+  in `Awake` instead of calling it every frame.
+* `RequireComponent(typeof(T))` makes Unity auto-add the required component
+  when the script is added in the inspector.
+
+## The Component pattern in practice
+
+```csharp
+[RequireComponent(typeof(Rigidbody))]
+public class PlayerController : MonoBehaviour
+{
+    private Rigidbody _rb;
+
+    private void Awake()
+    {
+        _rb = GetComponent<Rigidbody>(); // safe: RequireComponent guarantees it
+    }
+}
+```
+
+## Coroutines
+
+Coroutines let you write asynchronous-looking code that runs across multiple
+frames:
+
+```csharp
+private IEnumerator RespawnAfterDelay(float seconds)
+{
+    yield return new WaitForSeconds(seconds);
+    transform.position = _spawnPoint;
+}
+
+private void OnDeath() => StartCoroutine(RespawnAfterDelay(2f));
+```
+
+* `yield return null;` waits one frame.
+* `yield return new WaitForFixedUpdate();` waits until the next physics step.
+* `yield return new WaitUntil(() => _isGrounded);` waits for a condition.
+
+## Inspector best practices
+
+* Use `[Header]`, `[Tooltip]`, `[Range]`, `[SerializeField]` to keep the
+  inspector tidy.
+* Prefer `private` + `[SerializeField]` over `public` for fields that should
+  not be touched by other scripts but should be editable in the inspector.
+* Use `[System.Serializable]` on structs/classes to make them expandable in
+  the inspector.

unity_agent/knowledge/entries/unity_input_system.md

@@ -0,0 +1,154 @@
+# Unity Input System
+
+Unity offers two input systems:
+
+1. **Input Manager (legacy)** -- `Input.GetAxis`, `Input.GetKeyDown`. The
+   default in 2022.3 LTS. Used by every generated script in this project.
+2. **Input System package** -- the new event-driven API. Available via the
+   `com.unity.inputsystem` package.
+
+## Input Manager (legacy)
+
+### Axes
+
+The legacy system reads virtual axes defined in
+`Edit > Project Settings > Input Manager`. The defaults include:
+
+| Axis name     | Default keys                    |
+|---------------|---------------------------------|
+| `Horizontal`  | A/D, Arrow Left/Right           |
+| `Vertical`    | W/S, Arrow Up/Down              |
+| `Mouse X`     | Mouse delta X                   |
+| `Mouse Y`     | Mouse delta Y                   |
+| `Jump`        | Space                           |
+| `Fire1`       | Left Ctrl / Mouse 0             |
+| `Fire2`       | Right Alt / Mouse 1             |
+| `Fire3`       | Left Shift / Mouse 2            |
+
+### Reading axes
+
+```csharp
+float x = Input.GetAxisRaw("Horizontal"); // -1, 0, +1 (no smoothing)
+float y = Input.GetAxis("Vertical");      // smoothed, -1..+1
+Vector2 move = new Vector2(x, y);
+move = Vector2.ClampMagnitude(move, 1f);  // prevent diagonal speed boost
+```
+
+* Use `GetAxisRaw` for responsive arcade movement; `GetAxis` for smooth
+  camera-style axes.
+* Always clamp the magnitude of a 2-axis vector -- otherwise diagonal
+  movement is ~1.41x faster than cardinal.
+
+### Keys and buttons
+
+```csharp
+if (Input.GetKeyDown(KeyCode.Space))      Jump();
+if (Input.GetKey(KeyCode.LeftShift))      Sprint();
+if (Input.GetKeyUp(KeyCode.E))            Interact();
+if (Input.GetMouseButtonDown(0))          Fire();
+if (Input.GetMouseButton(0))              FireContinuous();
+```
+
+| Method                | Fires when                                |
+|-----------------------|-------------------------------------------|
+| `GetKey`              | Every frame the key is held               |
+| `GetKeyDown`          | Only on the frame the key was pressed     |
+| `GetKeyUp`            | Only on the frame the key was released    |
+| `GetMouseButton`      | Every frame the button is held            |
+| `GetMouseButtonDown`  | Only on the frame the button went down    |
+
+### Mouse position and delta
+
+```csharp
+Vector3 mousePos = Input.mousePosition;          // screen-space pixels
+float dx = Input.GetAxis("Mouse X");             // smoothed delta
+float rawDx = Input.GetAxisRaw("Mouse X");
+```
+
+To lock the cursor for first-person look:
+
+```csharp
+Cursor.lockState = CursorLockMode.Locked;        // hide + center
+Cursor.visible = false;
+```
+
+## Mouse-look recipe (first-person)
+
+```csharp
+private float _pitch;
+
+private void Update()
+{
+    float mx = Input.GetAxisRaw("Mouse X") * sensitivity;
+    float my = Input.GetAxisRaw("Mouse Y") * sensitivity;
+
+    transform.Rotate(Vector3.up * mx);
+    _pitch = Mathf.Clamp(_pitch - my, -85f, 85f);
+    cameraTransform.localRotation = Quaternion.Euler(_pitch, 0f, 0f);
+}
+```
+
+## Mouse-look recipe (third-person orbit)
+
+For a third-person camera we accumulate a **yaw** and **pitch** and build a
+rotation each frame:
+
+```csharp
+_yaw   += Input.GetAxis("Mouse X") * sensitivity;
+_pitch -= Input.GetAxis("Mouse Y") * sensitivity;
+_pitch  = Mathf.Clamp(_pitch, -30f, 75f);
+Quaternion rotation = Quaternion.Euler(_pitch, _yaw, 0f);
+Vector3 position = pivot + rotation * new Vector3(0f, height, -distance);
+```
+
+The `ThirdPersonCamera.cs` generator follows exactly this pattern.
+
+## Input System package (new)
+
+When the project has the Input System package active, the legacy `Input`
+class will throw or return zeros unless `Project Settings > Player > Active Input Handling = Both`.
+
+The new API is event-based:
+
+```csharp
+[SerializeField] private InputActionAsset actions;
+private InputAction _moveAction;
+
+private void OnEnable()
+{
+    _moveAction = actions.FindAction("Move");
+    _moveAction.performed += OnMove;
+    _moveAction.Enable();
+}
+
+private void OnMove(InputAction.CallbackContext ctx) => _moveInput = ctx.ReadValue<Vector2>();
+private void OnDisable() => _moveAction.Disable();
+```
+
+For the generated project we keep Active Input Handling on **Both** so the
+legacy `Input` calls in the generated scripts keep working.
+
+## Touch and mobile
+
+For mobile, read `Input.touches` (legacy) or the new Input System's
+`Pointer`/`Touchscreen`:
+
+```csharp
+foreach (Touch t in Input.touches)
+{
+    if (t.phase == TouchPhase.Began) HandleTap(t.position);
+}
+```
+
+The generated scripts are desktop-first; you would add a virtual joystick
+overlay for mobile ports.
+
+## Common pitfalls
+
+* Reading `Input` in `FixedUpdate` -- the input system updates once per
+  frame, but `FixedUpdate` may run 0..N times per frame, so you will drop
+  or duplicate inputs.
+* Using `Input.GetAxis` for physics forces -- the smoothed value can cause
+  floaty controls. Prefer `GetAxisRaw` and apply your own smoothing.
+* Forgetting to lock the cursor in an FPS leads to the camera spinning
+  when the cursor leaves the game window.