/hz-unity-fbx-import

name: hz-unity-fbx-import
license: Apache-2.0
description: Ensures complete FBX URLs or absolute paths are used when importing external 3D models into Unity projects targeting Meta Quest and Horizon OS. Use when adding FBX files, 3D models, or external assets.

Unity FBX Import with Full URLs

This skill ensures that when importing external 3D models (FBX files) into Unity using the Unity MCP `Unity_ImportExternalModel` tool, full and complete URLs are always provided, preventing import failures due to incomplete paths.

When to use this skill

Use this skill automatically whenever:

• Importing FBX files from external sources
• Adding 3D models to the Unity project
• Loading assets from URLs or file paths
• User mentions: "import model", "add FBX", "load 3D asset", "bring in model"
• Using the `Unity_ImportExternalModel` tool from Unity MCP

Core principle

**ALWAYS use complete, fully-qualified URLs for FBX files.**

Never use relative paths, partial URLs, or assume path completion. The `FbxUrl` parameter must be a complete URL or absolute file path.

Instructions

Step 1: Identify the FBX source

When a user requests to import a model, determine the source:

1. **Remote URL** (HTTP/HTTPS):

• Must start with `http://` or `https://`
• Must include the full domain and path
• Filename must end with `.fbx` or `.zip`
• **IMPORTANT**: Include ALL query parameters and tokens after the extension
• Query parameters (like `?param=value&other=data`) are required for authentication
• Example: `https://example.com/models/character.fbx?token=abc123&auth=xyz`
• Example: `https://cdn.fbcdn.net/path/file.fbx?_nc_gid=xxx&_nc_oc=yyy&oh=zzz`

2. **Local file** (file system):

• Must be an absolute path (not relative)
• Windows: `C:/Users/name/Downloads/model.fbx`
• Unix/Mac: `/home/user/models/model.fbx`
• Must end with `.fbx` or `.zip`

3. **ZIP archive**:

• Can be URL or local path
• Must contain an FBX file inside
• Example: `https://example.com/assets.zip`

Step 2: Validate the URL format

Before calling `Unity_ImportExternalModel`, verify the URL:

**CRITICAL**: For URLs with query parameters (like `?token=...&auth=...`), you MUST include the ENTIRE URL including all parameters. Query parameters often contain authentication tokens required for download.

Valid examples:

• `https://cdn.example.com/assets/models/chair.fbx`
• `https://cdn.example.com/models/chair.fbx?token=abc123&auth=xyz789` (with query params)
• `https://scontent.fbcdn.net/model.fbx?_nc_gid=xxx&_nc_oc=yyy&oh=zzz` (Meta CDN with auth)
• `http://localhost:8000/models/character.fbx`
• `file:///C:/Users/name/Downloads/robot.fbx`
• `C:/Projects/Models/tree.fbx` (Windows absolute)
• `/home/user/assets/car.fbx` (Unix absolute)
• `https://github.com/user/repo/releases/download/v1.0/model.zip`

Invalid examples (never use these):

• `models/chair.fbx` (relative path)
• `~/Downloads/robot.fbx` (tilde expansion not supported)
• `example.com/model.fbx` (missing protocol)
• `../assets/model.fbx` (relative path)
• `model.fbx` (no path at all)

Step 3: Get required parameters

The `Unity_ImportExternalModel` tool requires:

1. **Name** (required):

• Simple identifier (single word, no spaces)
• Use alphanumeric characters and underscores/hyphens
• Example: `office_chair`, `character_01`, `tree_oak`

2. **FbxUrl** (required):

• **MUST be a complete, full URL or absolute path**
• No relative paths allowed
• Include protocol for remote URLs (`http://`, `https://`)

3. **Height** (required):

• Desired height in Unity units (meters)
• Reasonable values: 0.1 to 10.0 for most objects
• Example: 1.8 for human-sized character, 2.0 for chair

4. **AlbedoTextureUrl** (optional):

• Full URL to texture file (same rules as FbxUrl)
• Can be local file or remote URL
• Common formats: `.png`, `.jpg`, `.jpeg`

Step 4: Call Unity_ImportExternalModel with full URL

Use the Unity MCP tool with complete parameters:

{
  "Name": "office_chair",
  "FbxUrl": "https://example.com/models/office_chair.fbx",
  "Height": 1.0,
  "AlbedoTextureUrl": "https://example.com/textures/chair_diffuse.png"
}

**Never omit the protocol or use partial paths.**

Step 5: Handle the import result

After calling `Unity_ImportExternalModel`:

1. **Check for success**:

• Tool returns `success: true` if import succeeded
• Result includes GameObject and Prefab information
• Note the bounds (size and center) for placement

2. **Extract important data**:

• GameObject instance ID and name
• Prefab path for reuse
• World size and center (for placement operations)

3. **Report to user**:

• Confirm successful import
• Show the GameObject name and prefab path
• Mention the size and position
• Suggest next steps (placement, scaling, etc.)

Step 6: Use with unity-placement skill

After importing, use the bounds information with the `unity-placement` skill for proper positioning:

The imported model has:
- Size: [width, height, depth]
- Center: [x, y, z]
- Prefab: Assets/Prefabs/name.prefab

Consider the size when placing relative to other objects.

Handling user-provided paths

If user provides a partial path

When the user gives an incomplete path, **ask for the complete path**:

User: "Import models/car.fbx"

Ask for clarification: "I need the complete path to the FBX file. Is it:

• A remote URL? (e.g., https://example.com/models/car.fbx)
• A local file? Please provide the absolute path (e.g., C:/Projects/models/car.fbx)

What is the full path to car.fbx?"

If user provides a URL without protocol

User: "Import from example.com/models/chair.fbx"

Clarify the protocol: "Should this be:

• https://example.com/models/chair.fbx (HTTPS)
• http://example.com/models/chair.fbx (HTTP)

Which protocol should I use?"

If user provides a relative path

User: "Import ../models/tree.fbx"

Request absolute path: "Relative paths aren't supporte