hz-unity-fbx-import

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unity FBX Import with Full URLs

Unity中使用完整URL导入FBX

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.

本技能确保在使用Unity MCP的

Unity_ImportExternalModel

工具将外部3D模型（FBX文件）导入Unity时，始终提供完整的URL，避免因路径不完整导致导入失败。

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

在以下场景中自动使用本技能：

从外部源导入FBX文件
向Unity项目添加3D模型
从URL或文件路径加载资源
用户提及：“导入模型”、“添加FBX”、“加载3D资源”、“导入模型”
使用Unity MCP中的
```
Unity_ImportExternalModel
```
工具

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.

始终为FBX文件使用完整的、完全限定的URL。

绝不要使用相对路径、部分URL，或假设路径会自动补全。

FbxUrl

参数必须是完整的URL或绝对文件路径。

Instructions

操作步骤

Step 1: Identify the FBX source

步骤1：确定FBX源

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

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
```
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
```
ZIP archive:
- Can be URL or local path
- Must contain an FBX file inside
- Example:
```
https://example.com/assets.zip
```

当用户请求导入模型时，先确定源类型：

远程URL（HTTP/HTTPS）：
- 必须以
```
http://
```
  或
```
https://
```
  开头
- 必须包含完整的域名和路径
- 文件名必须以
```
.fbx
```
  或
```
.zip
```
  结尾
- 重要提示：包含扩展名后的所有查询参数和令牌
- 查询参数（如
```
?param=value&other=data
```
  ）是身份验证所需的
- 示例：
```
https://example.com/models/character.fbx?token=abc123&auth=xyz
```
- 示例：
```
https://cdn.fbcdn.net/path/file.fbx?_nc_gid=xxx&_nc_oc=yyy&oh=zzz
```
本地文件（文件系统）：
- 必须是绝对路径（而非相对路径）
- Windows：
```
C:/Users/name/Downloads/model.fbx
```
- Unix/Mac：
```
/home/user/models/model.fbx
```
- 必须以
```
.fbx
```
  或
```
.zip
```
  结尾
ZIP压缩包：
- 可以是URL或本地路径
- 内部必须包含FBX文件
- 示例：
```
https://example.com/assets.zip
```

Step 2: Validate the URL format

步骤2：验证URL格式

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)

在调用

Unity_ImportExternalModel

之前，验证URL：

关键提示：对于带有查询参数（如

?token=...&auth=...

）的URL，必须包含完整的URL及所有参数。查询参数通常包含下载所需的身份验证令牌。

有效示例：

https://cdn.example.com/assets/models/chair.fbx

https://cdn.example.com/models/chair.fbx?token=abc123&auth=xyz789

（带查询参数）

https://scontent.fbcdn.net/model.fbx?_nc_gid=xxx&_nc_oc=yyy&oh=zzz

（带身份验证的Meta CDN）

http://localhost:8000/models/character.fbx

file:///C:/Users/name/Downloads/robot.fbx

```
C:/Projects/Models/tree.fbx
```
（Windows绝对路径）
```
/home/user/assets/car.fbx
```
（Unix绝对路径）

https://github.com/user/repo/releases/download/v1.0/model.zip

无效示例（绝不要使用）：

```
models/chair.fbx
```
（相对路径）
```
~/Downloads/robot.fbx
```
（不支持波浪号展开）
```
example.com/model.fbx
```
（缺少协议）
```
../assets/model.fbx
```
（相对路径）
```
model.fbx
```
（无路径）

Step 3: Get required parameters

步骤3：获取所需参数

The

Unity_ImportExternalModel

tool requires:

Name (required):
- Simple identifier (single word, no spaces)
- Use alphanumeric characters and underscores/hyphens
- Example:
```
office_chair
```
  ,
```
character_01
```
  ,
```
tree_oak
```
FbxUrl (required):
- MUST be a complete, full URL or absolute path
- No relative paths allowed
- Include protocol for remote URLs (
```
http://
```
  ,
```
https://
```
  )
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
AlbedoTextureUrl (optional):
- Full URL to texture file (same rules as FbxUrl)
- Can be local file or remote URL
- Common formats:
```
.png
```
  ,
```
.jpg
```
  ,
```
.jpeg
```

Unity_ImportExternalModel

工具需要以下参数：

Name（必填）：
- 简单标识符（单个单词，无空格）
- 使用字母数字字符及下划线/连字符
- 示例：
```
office_chair
```
  ,
```
character_01
```
  ,
```
tree_oak
```
FbxUrl（必填）：
- 必须是完整的URL或绝对路径
- 不允许使用相对路径
- 远程URL需包含协议（
```
http://
```
  ,
```
https://
```
  ）
Height（必填）：
- Unity单位（米）下的期望高度
- 合理值：大多数对象为0.1到10.0
- 示例：人物角色为1.8，椅子为2.0
AlbedoTextureUrl（可选）：
- 纹理文件的完整URL（规则与FbxUrl相同）
- 可以是本地文件或远程URL
- 常见格式：
```
.png
```
  ,
```
.jpg
```
  ,
```
.jpeg
```

Step 4: Call Unity_ImportExternalModel with full URL

步骤4：使用完整URL调用Unity_ImportExternalModel

Use the Unity MCP tool with complete parameters:

json

{
  "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.

使用完整参数调用Unity MCP工具：

json

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

绝不要省略协议或使用部分路径。

Step 5: Handle the import result

步骤5：处理导入结果

After calling

Unity_ImportExternalModel

Check for success:
- Tool returns
```
success: true
```
  if import succeeded
- Result includes GameObject and Prefab information
- Note the bounds (size and center) for placement
Extract important data:
- GameObject instance ID and name
- Prefab path for reuse
- World size and center (for placement operations)
Report to user:
- Confirm successful import
- Show the GameObject name and prefab path
- Mention the size and position
- Suggest next steps (placement, scaling, etc.)

调用

Unity_ImportExternalModel

后：

检查是否成功：
- 工具返回
```
success: true
```
  表示导入成功
- 结果包含GameObject和Prefab信息
- 记录边界（大小和中心）以便放置
提取重要数据：
- GameObject实例ID和名称
- 可复用的Prefab路径
- 世界大小和中心（用于放置操作）
向用户反馈：
- 确认导入成功
- 显示GameObject名称和Prefab路径
- 提及大小和位置
- 建议下一步操作（放置、缩放等）

Step 6: Use with unity-placement skill

步骤6：结合unity-placement技能使用

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.

导入完成后，使用边界信息结合

unity-placement

技能进行正确定位：

导入的模型具有：
- 大小：[宽度, 高度, 深度]
- 中心：[x, y, z]
- Prefab：Assets/Prefabs/name.prefab

放置时请考虑其与其他对象的相对大小。

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

当用户给出不完整路径时，询问完整路径：

用户：“导入models/car.fbx”

请求澄清： “我需要FBX文件的完整路径。它是：

远程URL？（例如：https://example.com/models/car.fbx）
本地文件？请提供绝对路径（例如：C:/Projects/models/car.fbx）

car.fbx的完整路径是什么？”

If user provides a URL without protocol

若用户提供无协议的URL

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

用户：“从example.com/models/chair.fbx导入”

澄清协议： “应该使用：

我应该使用哪种协议？”

If user provides a relative path

若用户提供相对路径

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

Request absolute path: "Relative paths aren't supported. Please provide the absolute path to tree.fbx.

For example:

Windows: C:/Projects/models/tree.fbx
Mac/Linux: /home/user/projects/models/tree.fbx

What is the full path?"

用户：“导入../models/tree.fbx”

请求绝对路径： “不支持相对路径。请提供tree.fbx的绝对路径。

例如：

Windows：C:/Projects/models/tree.fbx
Mac/Linux：/home/user/projects/models/tree.fbx

完整路径是什么？”

Best practices

最佳实践

Always verify URL format before calling
```
Unity_ImportExternalModel
```
Never assume paths - always use what's explicitly provided or ask for clarification
Prefer absolute paths over any form of relative path
Include protocol for all remote URLs (http://, https://)
Validate file extension - must be .fbx or .zip
Use simple names - alphanumeric with underscores/hyphens only
Set reasonable heights - 0.1 to 10.0 for most objects
Check import results - verify success and extract bounds data
Coordinate with unity-placement - use bounds for subsequent positioning

调用
Unity_ImportExternalModel
前始终验证URL格式
绝不假设路径 - 始终使用明确提供的路径，或请求澄清
优先使用绝对路径而非任何形式的相对路径
所有远程URL都包含协议（http://, https://）
验证文件扩展名 - 必须是.fbx或.zip
使用简单名称 - 仅使用字母数字及下划线/连字符
设置合理高度 - 大多数对象为0.1到10.0
检查导入结果 - 验证成功并提取边界数据
与unity-placement协作 - 使用边界数据进行后续定位

Error prevention checklist

错误预防检查清单

Before calling

Unity_ImportExternalModel

, verify:

```
FbxUrl
```
is a complete URL or absolute path
URL includes protocol if remote (http:// or https://)
ALL query parameters are included (everything after ? in the URL)
Path is absolute if local (starts with C:/ or /)
No relative path components (no ../ or ./)
No tilde expansion (no ~/)
Filename ends with .fbx or .zip (query params can follow)
```
Name
```
parameter is a simple identifier (no spaces)
```
Height
```
is a reasonable positive number
```
AlbedoTextureUrl
```
(if provided) is also a full URL/path with all params

调用

Unity_ImportExternalModel

前，验证以下内容：

```
FbxUrl
```
是完整的URL或绝对路径
远程URL包含协议（http://或https://）
包含所有查询参数（URL中?之后的所有内容）
本地路径是绝对路径（以C:/或/开头）
无相对路径组件（无../或./）
无波浪号展开（无~/）
文件名以.fbx或.zip结尾（查询参数可在其后）
```
Name
```
参数是简单标识符（无空格）
```
Height
```
是合理的正数
```
AlbedoTextureUrl
```
（若提供）也是包含所有参数的完整URL/路径

Fallback: When Unity_ImportExternalModel is unavailable

回退方案：当Unity_ImportExternalModel不可用时

Unity_ImportExternalModel

is not available but other Unity MCP tools (like

Unity_RunCommand

) are working, there are two options.

如果

Unity_ImportExternalModel

不可用，但其他Unity MCP工具（如

Unity_RunCommand

）可正常使用，有两种选择。

Option A: Enable the tool in Unity

选项A：在Unity中启用该工具

Tell the user:

"The

Unity_ImportExternalModel

tool is not currently enabled. To enable it:

In Unity, go to Project Settings -> AI -> Unity MCP Server
Under the Core section, toggle on
```
Unity_ImportExternalModel
```
The tool will become available immediately — no restart needed."

告知用户：

“当前未启用

Unity_ImportExternalModel

工具。要启用它：

在Unity中，前往Project Settings -> AI -> Unity MCP Server
在Core部分，开启
```
Unity_ImportExternalModel
```
的开关
工具将立即可用——无需重启。”

Option B: Manual import via Unity_RunCommand

选项B：通过Unity_RunCommand手动导入

If the user cannot or does not want to enable the tool, read

FALLBACK_MANUAL_IMPORT.md

(next to this file) for a step-by-step guide to replicate the import pipeline using

Unity_RunCommand

, based on the reference implementation in the

com.unity.ai.assistant

package.

如果用户无法或不想启用该工具，请阅读本文件旁的

FALLBACK_MANUAL_IMPORT.md

，获取基于

com.unity.ai.assistant

包中的参考实现，使用

Unity_RunCommand

复制导入流程的分步指南。

Quick reference

快速参考

Required format for FbxUrl

FbxUrl的必填格式

Source Type	Format	Example
Remote HTTPS	`https://domain/path/file.fbx`	`https://cdn.example.com/models/chair.fbx`
Remote HTTP	`http://domain/path/file.fbx`	`http://localhost:8000/model.fbx`
Local Windows	`C:/path/to/file.fbx`	`C:/Users/name/Downloads/robot.fbx`
Local Mac/Linux	`/path/to/file.fbx`	`/home/user/models/tree.fbx`
ZIP archive	Same as above with `.zip`	`https://example.com/pack.zip`

源类型	格式	示例
远程HTTPS	`https://domain/path/file.fbx`	`https://cdn.example.com/models/chair.fbx`
远程HTTP	`http://domain/path/file.fbx`	`http://localhost:8000/model.fbx`
本地Windows	`C:/path/to/file.fbx`	`C:/Users/name/Downloads/robot.fbx`
本地Mac/Linux	`/path/to/file.fbx`	`/home/user/models/tree.fbx`
ZIP压缩包	与上述格式相同，后缀为 `.zip`	`https://example.com/pack.zip`

Integration with other skills

与其他技能的集成

With unity-placement

与unity-placement集成

After importing, use the returned bounds with

unity-placement

Imported model "robot_character":
- Size: [0.6, 1.8, 0.4]
- Center: [0, 0.9, 0]
- Prefab: Assets/Prefabs/robot_character.prefab

To place this robot on the platform:
[Use unity-placement skill with the size data]

导入完成后，使用返回的边界数据结合

unity-placement

：

导入的模型“robot_character”：
- 大小：[0.6, 1.8, 0.4]
- 中心：[0, 0.9, 0]
- Prefab：Assets/Prefabs/robot_character.prefab

要将此机器人放置在平台上：
[使用unity-placement技能并传入大小数据]

Remember

谨记

The Unity MCP

Unity_ImportExternalModel

tool requires complete, absolute URLs or paths. When in doubt:

Ask the user for the complete path
Verify the URL format before calling the tool
Include the protocol for remote URLs
Use absolute paths for local files
Never guess or auto-complete partial paths
Never use relative paths or tilde expansion

Goal: Prevent import failures by ensuring every

FbxUrl

parameter is a valid, complete, fully-qualified URL or absolute file path.

Unity MCP的

Unity_ImportExternalModel

工具要求完整的绝对URL或路径。如有疑问：

向用户询问完整路径
调用工具前验证URL格式
远程URL包含协议
本地文件使用绝对路径
绝不猜测或自动补全部分路径
绝不使用相对路径或波浪号展开

目标：确保每个

FbxUrl

参数都是有效的、完整的、完全限定的URL或绝对文件路径，从而避免导入失败。