Feature/multi-view screenshot (#840)

* chore: update Unity package to beta version 9.4.8-beta.8

* feat: contact sheet compositor for batch screenshots

- Batch surround/orbit modes now return a single composite contact sheet image
- Added orbit mode with configurable azimuth, elevations, distance, FOV
- Contact sheet tiles are labeled with compass directions (front, back_left, etc.)
- CLI saves contact sheet PNGs to Assets/Screenshots/ by default
- ScreenshotUtility: RenderCameraToTexture, ComposeContactSheet with 5x7 pixel font
- Server manage_scene.py: orbit params forwarding
- CLI raw command: nargs fix for Windows argument splitting
- Updated docs: CLI_USAGE, CLI_EXAMPLE, SKILL.md, tools-reference

* Doc Update

---------

Co-authored-by: GitHub Actions <actions@github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: 3 people

.claude/skills/unity-mcp-skill/references/tools-reference.md

@@ -109,7 +109,7 @@ manage_scene(
     include_transform=False      # bool - include local transforms
 )
 
-# Screenshot (file only — saves to Assets/)
+# Screenshot (file only — saves to Assets/Screenshots/)
 manage_scene(action="screenshot")
 
 # Screenshot with inline image (base64 PNG returned to AI)
@@ -120,13 +120,13 @@ manage_scene(
     max_resolution=512           # int, optional - downscale cap (default 640)
 )
 
-# Batch surround (6 angles around scene bounds, no file saved)
+# Batch surround — contact sheet of 6 fixed angles (front/back/left/right/top/bird_eye)
 manage_scene(
     action="screenshot",
-    batch="surround",            # str - "surround" for 6-angle capture
-    max_resolution=256           # int - keep low for batch (6 images)
+    batch="surround",            # str - "surround" for 6-angle contact sheet
+    max_resolution=256           # int - per-tile resolution cap
 )
-# Returns: front, back, left, right, top, bird_eye views
+# Returns: single composite contact sheet image with labeled tiles
 
 # Batch surround centered on a specific target
 manage_scene(
@@ -136,6 +136,19 @@ manage_scene(
     max_resolution=256
 )
 
+# Batch orbit — configurable multi-angle grid around a target
+manage_scene(
+    action="screenshot",
+    batch="orbit",               # str - "orbit" for configurable angle grid
+    look_at="Player",            # str|int|list[float] - target to orbit around
+    orbit_angles=8,              # int, default 8 - number of azimuth steps
+    orbit_elevations=[0, 30],    # list[float], default [0, 30, -15] - vertical angles in degrees
+    orbit_distance=10,           # float, optional - camera distance (auto-fit if omitted)
+    orbit_fov=60,                # float, default 60 - camera FOV in degrees
+    max_resolution=256           # int - per-tile resolution cap
+)
+# Returns: single composite contact sheet (angles × elevations tiles in a grid)
+
 # Positioned screenshot (temp camera at viewpoint, no file saved)
 manage_scene(
     action="screenshot",

MCPForUnity/Editor/Tools/ManageScene.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Collections.Generic;
 using System.IO;
 using System.Linq;
 using UnityEngine;
@@ -270,6 +271,232 @@ public static (string base64, int width, int height) RenderCameraToBase64(Camera
             }
         }
 
+        /// <summary>
+        /// Renders a camera to a Texture2D without saving to disk.
+        /// Caller owns the returned texture and must destroy it.
+        /// </summary>
+        public static Texture2D RenderCameraToTexture(Camera camera, int maxResolution = 640)
+        {
+            if (camera == null) throw new ArgumentNullException(nameof(camera));
+
+            int width = Mathf.Max(1, camera.pixelWidth > 0 ? camera.pixelWidth : Screen.width);
+            int height = Mathf.Max(1, camera.pixelHeight > 0 ? camera.pixelHeight : Screen.height);
+
+            RenderTexture prevRT = camera.targetTexture;
+            RenderTexture prevActive = RenderTexture.active;
+            var rt = RenderTexture.GetTemporary(width, height, 24, RenderTextureFormat.ARGB32);
+            Texture2D tex = null;
+            try
+            {
+                camera.targetTexture = rt;
+                camera.Render();
+
+                RenderTexture.active = rt;
+                tex = new Texture2D(width, height, TextureFormat.RGBA32, false);
+                tex.ReadPixels(new Rect(0, 0, width, height), 0, 0);
+                tex.Apply();
+
+                int targetMax = maxResolution > 0 ? maxResolution : 640;
+                if (width > targetMax || height > targetMax)
+                {
+                    var downscaled = DownscaleTexture(tex, targetMax);
+                    DestroyTexture(tex);
+                    tex = null;
+                    return downscaled;
+                }
+                var result = tex;
+                tex = null; // transfer ownership to caller
+                return result;
+            }
+            finally
+            {
+                camera.targetTexture = prevRT;
+                RenderTexture.active = prevActive;
+                RenderTexture.ReleaseTemporary(rt);
+                DestroyTexture(tex);
+            }
+        }
+
+        /// <summary>
+        /// Composites a list of tile textures into a single contact-sheet grid image.
+        /// Labels are drawn as white text on a dark banner at the bottom of each tile.
+        /// Returns base64 PNG plus dimensions. Destroys all input tile textures.
+        /// </summary>
+        public static (string base64, int width, int height) ComposeContactSheet(
+            List<Texture2D> tiles, List<string> labels, int padding = 4)
+        {
+            if (tiles == null || tiles.Count == 0)
+                throw new ArgumentException("No tiles to compose.", nameof(tiles));
+
+            int tileW = tiles[0].width;
+            int tileH = tiles[0].height;
+            int count = tiles.Count;
+
+            // Calculate grid: prefer wider than tall (cols >= rows)
+            int cols = Mathf.CeilToInt(Mathf.Sqrt(count));
+            int rows = Mathf.CeilToInt((float)count / cols);
+
+            int labelHeight = Mathf.Max(14, tileH / 12);
+            int cellW = tileW + padding;
+            int cellH = tileH + labelHeight + padding;
+
+            int sheetW = cols * cellW + padding;
+            int sheetH = rows * cellH + padding;
+
+            Texture2D sheet = null;
+            try
+            {
+                sheet = new Texture2D(sheetW, sheetH, TextureFormat.RGBA32, false);
+
+                // Build the full sheet in a Color32[] buffer, then upload once
+                var bgColor = new Color32(30, 30, 30, 255);
+                Color32[] sheetPixels = new Color32[sheetW * sheetH];
+                for (int i = 0; i < sheetPixels.Length; i++) sheetPixels[i] = bgColor;
+
+                // Track label draw requests so we can apply them after the bulk upload
+                var labelDraws = new List<(string text, int x, int y, int h)>();
+
+                for (int idx = 0; idx < count; idx++)
+                {
+                    int col = idx % cols;
+                    int row = idx / cols;
+                    // Place tiles top-left to bottom-right (Unity Texture2D y=0 is bottom)
+                    int x = padding + col * cellW;
+                    int y = sheetH - padding - (row + 1) * cellH + padding;
+
+                    // Copy tile pixels row-by-row using bulk operations
+                    Color32[] tilePixels = tiles[idx].GetPixels32();
+                    for (int ty = 0; ty < tileH; ty++)
+                    {
+                        int srcOffset = ty * tileW;
+                        int dstOffset = (y + labelHeight + ty) * sheetW + x;
+                        System.Array.Copy(tilePixels, srcOffset, sheetPixels, dstOffset, tileW);
+                    }
+
+                    // Draw label banner (dark background strip below tile)
+                    var bannerColor = new Color32(20, 20, 20, 220);
+                    for (int ly = 0; ly < labelHeight; ly++)
+                    {
+                        int dstOffset = (y + ly) * sheetW + x;
+                        for (int lx = 0; lx < tileW; lx++)
+                        {
+                            sheetPixels[dstOffset + lx] = bannerColor;
+                        }
+                    }
+
+                    // Queue label text drawing (applied after bulk pixel upload)
+                    if (labels != null && idx < labels.Count && !string.IsNullOrEmpty(labels[idx]))
+                    {
+                        labelDraws.Add((labels[idx], x + 3, y + 2, labelHeight - 4));
+                    }
+                }
+
+                // Upload all tile + banner pixels in one SetPixels32 call
+                sheet.SetPixels32(sheetPixels);
+
+                // Draw label text on top (small glyph-based writes, negligible cost)
+                foreach (var (text, lx, ly, lh) in labelDraws)
+                {
+                    DrawText(sheet, text, lx, ly, lh, Color.white);
+                }
+
+                sheet.Apply();
+
+                byte[] png = sheet.EncodeToPNG();
+                string b64 = System.Convert.ToBase64String(png);
+                return (b64, sheetW, sheetH);
+            }
+            finally
+            {
+                foreach (var tile in tiles) DestroyTexture(tile);
+                DestroyTexture(sheet);
+            }
+        }
+
+        private static void DrawText(Texture2D tex, string text, int startX, int startY, int charHeight, Color color)
+        {
+            // Simple 5x7 bitmap font for basic ASCII characters
+            int charWidth = Mathf.Max(4, charHeight * 5 / 7);
+            int spacing = Mathf.Max(1, charWidth / 5);
+            int x = startX;
+
+            foreach (char c in text)
+            {
+                if (x + charWidth > tex.width) break;
+                ulong glyph = GetGlyph(c);
+                if (glyph != 0)
+                {
+                    for (int row = 0; row < 7; row++)
+                    {
+                        for (int col = 0; col < 5; col++)
+                        {
+                            bool on = ((glyph >> ((6 - row) * 5 + (4 - col))) & 1) == 1;
+                            if (!on) continue;
+                            // Scale the 5x7 glyph to charWidth x charHeight
+                            int px0 = x + col * charWidth / 5;
+                            int px1 = x + (col + 1) * charWidth / 5;
+                            int py0 = startY + (6 - row) * charHeight / 7;
+                            int py1 = startY + (7 - row) * charHeight / 7;
+                            for (int py = py0; py < py1 && py < tex.height; py++)
+                                for (int px = px0; px < px1 && px < tex.width; px++)
+                                    tex.SetPixel(px, py, color);
+                        }
+                    }
+                }
+                x += charWidth + spacing;
+            }
+        }
+
+        private static ulong GetGlyph(char c)
+        {
+            // 5x7 pixel font stored as 35-bit values (row0=bits34-30 ... row6=bits4-0)
+            // Each row is 5 wide, MSB=left. Row 0 is top.
+            switch (char.ToUpperInvariant(c))
+            {
+                case 'A': return 0b01110_10001_10001_11111_10001_10001_10001UL;
+                case 'B': return 0b11110_10001_10001_11110_10001_10001_11110UL;
+                case 'C': return 0b01110_10001_10000_10000_10000_10001_01110UL;
+                case 'D': return 0b11100_10010_10001_10001_10001_10010_11100UL;
+                case 'E': return 0b11111_10000_10000_11110_10000_10000_11111UL;
+                case 'F': return 0b11111_10000_10000_11110_10000_10000_10000UL;
+                case 'G': return 0b01110_10001_10000_10111_10001_10001_01110UL;
+                case 'H': return 0b10001_10001_10001_11111_10001_10001_10001UL;
+                case 'I': return 0b01110_00100_00100_00100_00100_00100_01110UL;
+                case 'K': return 0b10001_10010_10100_11000_10100_10010_10001UL;
+                case 'L': return 0b10000_10000_10000_10000_10000_10000_11111UL;
+                case 'M': return 0b10001_11011_10101_10101_10001_10001_10001UL;
+                case 'N': return 0b10001_11001_10101_10011_10001_10001_10001UL;
+                case 'O': return 0b01110_10001_10001_10001_10001_10001_01110UL;
+                case 'R': return 0b11110_10001_10001_11110_10100_10010_10001UL;
+                case 'S': return 0b01110_10001_10000_01110_00001_10001_01110UL;
+                case 'T': return 0b11111_00100_00100_00100_00100_00100_00100UL;
+                case 'U': return 0b10001_10001_10001_10001_10001_10001_01110UL;
+                case 'V': return 0b10001_10001_10001_10001_01010_01010_00100UL;
+                case 'W': return 0b10001_10001_10001_10101_10101_11011_10001UL;
+                case 'Y': return 0b10001_10001_01010_00100_00100_00100_00100UL;
+                case '0': return 0b01110_10011_10101_10101_10101_11001_01110UL;
+                case '1': return 0b00100_01100_00100_00100_00100_00100_01110UL;
+                case '2': return 0b01110_10001_00001_00010_00100_01000_11111UL;
+                case '3': return 0b01110_10001_00001_00110_00001_10001_01110UL;
+                case '4': return 0b00010_00110_01010_10010_11111_00010_00010UL;
+                case '5': return 0b11111_10000_11110_00001_00001_10001_01110UL;
+                case '6': return 0b01110_10001_10000_11110_10001_10001_01110UL;
+                case '7': return 0b11111_00001_00010_00100_01000_01000_01000UL;
+                case '8': return 0b01110_10001_10001_01110_10001_10001_01110UL;
+                case '9': return 0b01110_10001_10001_01111_00001_10001_01110UL;
+                case 'J': return 0b00111_00010_00010_00010_00010_10010_01100UL;
+                case 'P': return 0b11110_10001_10001_11110_10000_10000_10000UL;
+                case 'Q': return 0b01110_10001_10001_10001_10101_10010_01101UL;
+                case 'X': return 0b10001_01010_00100_00100_00100_01010_10001UL;
+                case 'Z': return 0b11111_00001_00010_00100_01000_10000_11111UL;
+                case '-': return 0b00000_00000_00000_11111_00000_00000_00000UL;
+                case '_': return 0b00000_00000_00000_00000_00000_00000_11111UL;
+                case ' ': return 0UL;
+                case '+': return 0b00000_00100_00100_11111_00100_00100_00000UL;
+                default:  return 0UL;
+            }
+        }
+
         /// <summary>
         /// Downscales a Texture2D so that its longest edge is at most <paramref name="maxEdge"/> pixels.
         /// Uses bilinear filtering via a temporary RenderTexture blit.

MCPForUnity/Runtime/Helpers/ScreenshotUtility.cs

@@ -1,6 +1,6 @@
 {
   "name": "com.coplaydev.unity-mcp",
-  "version": "9.4.8-beta.7",
+  "version": "9.4.8-beta.8",
   "displayName": "MCP for Unity",
   "description": "A bridge that connects AI assistants to Unity via the MCP (Model Context Protocol). Allows AI clients like Claude Code, Cursor, and VSCode to directly control your Unity Editor for enhanced development workflows.\n\nFeatures automated setup wizard, cross-platform support, and seamless integration with popular AI development tools.\n\nJoin Our Discord: https://discord.gg/y4p8KfzrN4",
   "unity": "2021.3",