Hz Unity Fbx Import

Unity FBX Import with Full URLs

Importing an external 3D model fails most often for one reason: an incomplete source path. This skill ensures every FBX source is a complete, fully-qualified URL or absolute filesystem path, and walks the import through unity-cli.

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"

Core principle

ALWAYS use complete, fully-qualified URLs or absolute paths for FBX files.

Never use relative paths, partial URLs, or assume path completion.

unity command import_asset takes an absolute filesystem path — it does not download. Verified: passing a URL fails with "Source file 'https://…' does not exist." So a remote model is always two steps: download to disk, then import the local file.

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 — extract before importing
   • Example: https://example.com/assets.zip

Step 2: Validate the source format

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
• 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: Download remote sources to disk

Skip this step for a local file. Quote the URL so the shell doesn't split on & in query parameters — the single most common cause of a truncated, failing download.

# macOS / Linux
curl -fSL "https://example.com/models/office_chair.fbx" -o /tmp/office_chair.fbx

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://example.com/models/office_chair.fbx" -OutFile "$env:TEMP\office_chair.fbx"

Confirm the file exists and is non-empty before importing. A truncated or HTML error page saved as .fbx imports as a broken asset rather than failing loudly.

For a .zip, extract it first and locate the .fbx inside; import that.

Step 4: Import the file

unity status --format json          # look for state "ready"

# Validate first — reports what would be imported, writes nothing
unity command import_asset --source "C:/Users/name/Downloads/office_chair.fbx" \
  --path "Assets/Models/office_chair.fbx" --dry_run true --format json

# Then import for real
unity command import_asset --source "C:/Users/name/Downloads/office_chair.fbx" \
  --path "Assets/Models/office_chair.fbx" --format json

• --source is an absolute filesystem path to the external file.
• --path is the destination relative to the authoring root (usually Assets/), including the extension. The Assets/ prefix is optional.
• --confirm true is required only when overwriting an existing asset at the destination.
• --dry_run true validates and reports without writing — use it whenever the source came from a user.

Connecting, --project-path, and Safe Mode recovery are in the unity-cli skill.

Step 5: Set scale and rig type

import_asset copies and imports the file at its authored scale. Unlike a one-shot "import at height H" tool, normalizing size is a separate step:

unity command set_import_settings --asset "Assets/Models/office_chair.fbx" \
  --settings '{"globalScale": 0.46, "useFileScale": false}' --format json

Compute globalScale as targetHeight / currentHeight. For a humanoid rig also set animationType to Humanoid. See hz-unity-meta-movement-sdk-retargeting for why an oversized rig causes skewing, and for the ModelImporter fields involved.

Step 6: Instantiate, then get real bounds

unity command instantiate_prefab --prefab "Assets/Models/office_chair.fbx" --name office_chair --format json
unity command save_scene --format json

Then read the actual bounds — never assume the model's size. bounds is a computed property, so get_component_properties will not give it to you (a MeshRenderer read returns m_Materials, m_CastShadows and friends, no bounds). An imported FBX also puts its renderers on children of the instantiated root, so use GetBounds.cs from the unity-placement skill, which unions the child renderers' bounds:

unity command run_script --file AgentScripts/GetBounds.cs --entry GetBounds.Run \
  --args '[["office_chair"]]' --format json

Report the size and center to the user, and use them for any subsequent positioning.

Step 7: Report to user

• Confirm successful import
• Show the asset path and the instantiated GameObject name
• Show the measured size and center
• Suggest next steps (placement, scaling, material assignment)

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?"