Funplay Unity MCP execute_code：AI驱动Unity开发的代码沙盒与执行引擎

1. 项目概述：为什么execute_code是 MCP 皇冠上的明珠

在 AI 驱动的开发浪潮中，Model Context Protocol (MCP) 正迅速成为连接智能体与专业工具的“标准插座”。市面上涌现了成百上千的 MCP 工具，从代码分析、UI 设计到数据库管理，琳琅满目。但如果你问我，在 Unity 游戏开发这个垂直领域，哪一个 MCP 工具的功能是真正具有颠覆性、能让你从“辅助编程”跃升到“AI 协同创造”的，我会毫不犹豫地指向Funplay Unity MCP中的execute_code。

这个工具，远不止是一个“运行代码片段”的简单功能。它本质上是在 Unity Editor 内部，为 AI 智能体开辟了一个安全、即时、零残留的 C# 代码沙盒。想象一下，你正在和 Claude Code 或 Cursor 聊天，描述一个游戏功能：“给场景里那个角色添加一个碰到墙壁就反弹的物理效果。”传统工作流下，AI 要么只能生成代码文件让你手动拖入项目，要么调用一堆零散的 API 工具（创建组件、设置属性、查找对象），过程冗长且容易出错。而有了execute_code，AI 可以直接构思、编写、编译并执行一段完整的 C# 逻辑，整个过程在内存中完成，无需创建任何.cs文件，不会触发项目重载，执行结果（创建的对象、修改的属性、输出的日志）会结构化地返回给 AI，让它能基于此进行下一步决策。

这解决了 Unity 开发中一个核心痛点：快速迭代与验证的摩擦。美术调个参数要等编译，策划改个数值要等重载，程序员测试一个小功能也要经历“写代码-保存-等待编译-运行”的循环。execute_code将“思考-编码-验证”的循环压缩到了秒级，让 AI 真正成为了你坐在副驾驶的“即时执行伙伴”。因此，说它是 91 个 MCP 工具中最关键的一个，毫不为过。它不是锦上添花，而是重新定义了 AI 与游戏引擎交互的范式。

2.execute_code的核心设计哲学：在安全与能力之间走钢丝

execute_code的设计绝非简单的Eval函数封装。它需要在一个强大的、拥有几乎无限 API 访问能力的运行时（Unity Editor）中，安全地执行来自不可信源（AI 模型）的代码。这就像给一个顶级赛车手一辆没有刹车的 F1 赛车，既要让他跑出极限速度，又要确保不会车毁人亡。Funplay Unity MCP 的解决方案，体现了一系列精妙的权衡。

2.1 内存编译优先：零项目污染的核心理念

最核心的设计是“Roslyn-first in-memory compilation”。当 AI 提交一段 C# 代码片段时，Funplay MCP 会优先尝试使用 Unity 内置的 Roslyn 编译器在内存中进行编译。这与传统“生成脚本文件 -> 等待 Unity 重载编译”的方式有本质区别。

为什么这么做？

1. 速度：绕过文件 I/O 和 AssetDatabase 刷新，编译速度极快。
2. 无副作用：不会在Assets目录下产生任何临时或永久的.cs文件，保持了项目目录的绝对干净。这对于版本控制（Git）和项目维护至关重要，你不会被一堆AI_Generated_Script_001.cs之类的文件淹没。
3. 无中断：不会触发 Unity 的域重载（Domain Reload）。这意味着你的编辑器状态（如打开的窗口、选中的对象、播放模式）不会被打断，实现了无缝的交互体验。

实现路径：如果内存编译失败（例如，代码引用了项目特有的程序集），系统会有一个优雅的降级机制，但核心路径始终致力于避免写盘。这要求execute_code在调用前，会主动刷新AssetDatabase并等待所有挂起的编译完成，确保代码片段能访问到最新的项目类型和资产引用。

2.2 结构化执行上下文：让 AI 理解“发生了什么”

一个强大的执行工具，不仅要能“执行”，更要能“反馈”。execute_code引入了IFunplayCommand接口和ExecutionContext上下文对象，这是其设计中的点睛之笔。

public interface IFunplayCommand { void Execute(ExecutionContext ctx); }

AI 生成的代码需要封装在一个实现了此接口的类中。ExecutionContext为这段代码提供了三个关键能力：

1. 自动撤销注册：通过ctx.RegisterObjectCreation、RegisterObjectModification、RegisterDestroyObject方法，代码中对场景对象的任何增、删、改操作都会被自动记录到 Unity 的撤销栈中。这意味着你可以像对待普通编辑器操作一样，按Ctrl+Z撤销 AI 执行的所有更改。这赋予了 AI 操作以“公民权”，使其行为可逆、可管理。
2. 结构化日志：使用ctx.Log、LogWarning、LogError替代Debug.Log。这些日志会与执行结果一起，以结构化的 JSON 格式返回给 AI，帮助 AI 理解代码执行的流程、警告和错误。
3. 变更追踪与返回值：执行完毕后，ExecutionContext会收集一个详细的变更列表（创建了哪些 GameObject，修改了哪些组件的什么属性）并赋值给ctx.ReturnValue。这个列表和返回值会一并打包返回给 AI 客户端。

最终响应格式示例：

{ "success": true, "message": "Code executed successfully.", "data": { "logs": ["Created GameObject: Cube"], "created": [{"instanceId": 12345, "name": "Cube", "type": "GameObject"}], "modified": [], "destroyed": [], "returnValue": {"name": "Cube", "position": "(0,0,0)"} } }

有了这份“执行报告”，AI 就能确切知道它刚才做了什么，并基于instanceId等稳定标识符进行后续的链式操作，而不是每次都靠不稳定的名称或路径去查找对象。

2.3 安全边界：不是沙盒，是“有护栏的操场”

必须明确，execute_code不是一个完全隔离的沙盒。它运行在完整的 Unity Editor 托管环境中，理论上可以执行任何 C# 代码，包括调用System.IO删除文件、访问网络等危险操作。Funplay MCP 采取了一种务实的安全策略：

1. 默认启用安全检查：在Funplay > MCP Settings中，默认开启了安全检查和更严格的文件系统守卫。
2. 文件系统守卫：该守卫会拦截明显的破坏性代码模式，例如：
   • 广泛的System.IO写入操作。
   • 原始文件流操作。
   • 使用绝对路径、用户目录路径或包含路径遍历（..）的路径。
3. 客户端可覆盖：每个execute_code调用都可以携带一个可选的safety_checks参数，允许受信任的客户端（或用户）在明确知晓风险的情况下绕过某些检查。这体现了“权力下放”的设计思想，将最终的安全决策权部分交还给用户和其信任的 AI 代理。

这种设计哲学是：与其构建一个脆弱且限制重重的“金丝雀笼”，不如提供一个“有醒目护栏和警告标志的操场”。它默认阻止最常见的危险操作，但将高级用途和风险判断交给了专业人士。对于团队使用，建议在MCP Settings中保持严格模式，并通过项目规范和 AI 提示词来约束生成代码的行为。

3.execute_code的实战应用：从概念到可玩原型的加速器

理解了设计原理，我们来看看execute_code如何具体改变 Unity 开发工作流。我将通过几个渐进式的场景来展示其威力。

3.1 场景一：动态场景构建与脚本编排

任务：“创建一个简单的跑酷原型场景，包含一个玩家胶囊体、10个随机位置和旋转的平台，以及一个终点触发器。”

传统 AI 协作模式：

1. AI 调用create_primitive创建胶囊体。
2. AI 调用create_game_object创建第一个平台。
3. AI 调用set_transform设置平台位置（需要手动计算或生成随机数逻辑？这里可能卡住）。
4. 重复步骤2-3九次，每次都需要处理随机数生成和位置计算，交互次数极多。
5. AI 调用add_component为玩家添加角色控制器或脚本。
6. AI 调用create_script编写移动脚本，保存文件，触发编译。
7. 等待编译完成，AI 再调用assign_script或需要用户手动拖拽。
8. AI 调用add_component为终点添加 BoxCollider 和触发器脚本。 ... 过程繁琐，极易在步骤间丢失上下文。

execute_code驱动模式： AI 可以直接生成并执行如下单一片段：

using UnityEngine; using UnityEditor; using Funplay.Editor.Tools.Helpers; using Funplay.Editor.Tools.Scripting; public class CreateParkourScene : IFunplayCommand { public void Execute(ExecutionContext ctx) { // 1. 创建玩家 var player = GameObject.CreatePrimitive(PrimitiveType.Capsule); player.name = "Player"; player.transform.position = new Vector3(0, 1, 0); ctx.RegisterObjectCreation(player); ctx.Log($"Created player: {player.name}"); // 2. 添加并配置简单移动脚本（内存中编译，不写文件） var mover = player.AddComponent<PlayerMover>(); mover.speed = 5.0f; ctx.RegisterObjectModification(player); // 3. 创建10个随机平台 System.Random rng = new System.Random(); for (int i = 0; i < 10; i++) { var platform = GameObject.CreatePrimitive(PrimitiveType.Cube); platform.name = $"Platform_{i}"; float x = rng.Next(-20, 20); float z = rng.Next(-20, 20); platform.transform.position = new Vector3(x, 0, z); platform.transform.localScale = new Vector3(4, 0.5f, 2); platform.transform.rotation = Quaternion.Euler(0, rng.Next(0, 360), 0); ctx.RegisterObjectCreation(platform); ctx.Log($"Created platform: {platform.name} at {platform.transform.position}"); } // 4. 创建终点 var finish = new GameObject("FinishLine"); var collider = finish.AddComponent<BoxCollider>(); collider.isTrigger = true; finish.transform.position = new Vector3(25, 0.5f, 25); finish.transform.localScale = new Vector3(5, 2, 5); ctx.RegisterObjectCreation(finish); // 5. 将玩家设为选中状态，方便用户查看 Selection.activeGameObject = player; ctx.Log("Parkour scene setup complete. Player is selected."); ctx.ReturnValue = new { playerId = player.GetInstanceID(), platformCount = 10 }; } } // 内联定义的简单移动组件，仅用于此次执行 public class PlayerMover : MonoBehaviour { public float speed = 5.0f; void Update() { float moveX = Input.GetAxis("Horizontal") * speed * Time.deltaTime; float moveZ = Input.GetAxis("Vertical") * speed * Time.deltaTime; transform.Translate(moveX, 0, moveZ); } }

一次调用，完成所有工作。AI 收到了包含所有创建对象instanceId和日志的完整报告。整个场景从无到有，包含逻辑，仅在一次交互中完成。

3.2 场景二：运行时诊断与热修改

任务：“游戏运行时，角色跳跃力感觉太弱。请实时将场景中所有PlayerController组件的jumpForce参数增加 50%，并报告修改了哪些对象。”

这在没有execute_code时几乎是噩梦：你需要退出播放模式，找到脚本，修改，编译，重新运行。而现在：

public class AdjustJumpForce : IFunplayCommand { public void Execute(ExecutionContext ctx) { // 确保在播放模式 if (!EditorApplication.isPlaying) { ctx.LogError("Must be in Play Mode to adjust runtime components."); return; } var allPlayers = GameObject.FindObjectsOfType<PlayerController>(); var modifiedList = new List<string>(); foreach (var player in allPlayers) { float originalForce = player.jumpForce; player.jumpForce *= 1.5f; // 增加50% modifiedList.Add($"{player.gameObject.name}: {originalForce} -> {player.jumpForce}"); ctx.RegisterObjectModification(player.gameObject); // 标记修改，支持撤销 } ctx.Log($"Modified {allPlayers.Length} PlayerController instances."); ctx.ReturnValue = modifiedList; } }

AI 执行后，立即生效，你可以在游戏中马上感受到跳跃力的变化，并得到一份具体的修改清单。这为游戏平衡性调试和实时调参提供了前所未有的敏捷性。

3.3 场景三：批量数据处理与资产操作

任务：“扫描项目中的所有材质球，将那些使用Standard着色器且 Metallic 值为 1.0 的材质，复制一份并将着色器改为Standard (Specular setup)。”

这是一个典型的批量资产操作，涉及搜索、条件判断和修改。用离散的工具调用需要复杂的编排，而execute_code可以一气呵成：

public class MigrateMetallicMaterials : IFunplayCommand { public void Execute(ExecutionContext ctx) { string[] allMaterialGuids = AssetDatabase.FindAssets("t:Material"); int processedCount = 0; List<string> convertedMaterials = new List<string>(); foreach (string guid in allMaterialGuids) { string path = AssetDatabase.GUIDToAssetPath(guid); Material mat = AssetDatabase.LoadAssetAtPath<Material>(path); if (mat != null && mat.shader != null && mat.shader.name == "Standard") { if (mat.HasProperty("_Metallic") && Mathf.Approximately(mat.GetFloat("_Metallic"), 1.0f)) { // 复制材质 Material newMat = new Material(mat); newMat.shader = Shader.Find("Standard (Specular setup)"); // 将高光颜色设置为原金属颜色的近似值 if (mat.HasProperty("_Color")) { newMat.SetColor("_SpecColor", mat.GetColor("_Color") * 0.5f); } string newPath = path.Replace(".mat", "_Specular.mat"); AssetDatabase.CreateAsset(newMat, newPath); processedCount++; convertedMaterials.Add(System.IO.Path.GetFileName(newPath)); ctx.Log($"Converted: {path} -> {newPath}"); } } } AssetDatabase.SaveAssets(); ctx.Log($"Process completed. {processedCount} materials converted."); ctx.ReturnValue = convertedMaterials; } }

这段代码直接操作AssetDatabase，完成了查找、判断、创建新资产、保存等一系列操作。AI 通过一次执行，就完成了可能需要手动操作半小时的重复性工作。

4. 高级技巧与避坑指南：让execute_code如臂使指

掌握了基础应用，一些高级技巧和常见陷阱能让你和 AI 的合作更加顺畅。

4.1 性能优化：避免昂贵的每帧操作

execute_code虽然强大，但也要避免在代码片段中执行代价高昂的循环或每帧操作。例如，不要在Execute方法里写while (true)或调用GameObject.FindObjectsOfType在Update循环里。这会导致编辑器卡死。如果 AI 生成了这样的代码，你需要引导它：

“请将需要持续运行的逻辑封装到一个MonoBehaviour组件中，并通过AddComponent添加到游戏对象上，由 Unity 的生命周期管理，而不是在Execute方法中阻塞。”

4.2 正确处理异步与协程

Unity 中大量操作涉及异步或协程（如加载场景、发送网络请求）。execute_code的Execute方法是同步的。要执行异步操作，需要启动一个协程并妥善管理其生命周期。

public class AsyncLoadExample : IFunplayCommand { public void Execute(ExecutionContext ctx) { // 错误：直接调用异步方法会无法等待 // SceneManager.LoadSceneAsync("MyScene"); // 正确：通过 EditorCoroutine 或启动一个 MonoBehaviour 来运行协程 var runner = new GameObject("CoroutineRunner").AddComponent<CoroutineRunner>(); ctx.RegisterObjectCreation(runner.gameObject); runner.StartCoroutine(LoadSceneRoutine(ctx)); // 注意：runner 对象需要在适当时机销毁，避免残留 } private System.Collections.IEnumerator LoadSceneRoutine(ExecutionContext ctx) { var asyncOp = UnityEngine.SceneManagement.SceneManager.LoadSceneAsync("MyScene"); while (!asyncOp.isDone) { ctx.Log($"Loading progress: {asyncOp.progress:P0}"); yield return null; } ctx.Log("Scene loaded successfully."); // 清理临时 runner Object.DestroyImmediate(GameObject.Find("CoroutineRunner")); } } public class CoroutineRunner : MonoBehaviour { }

关键点：创建用于运行协程的临时 GameObject 后，务必通过ctx.RegisterObjectCreation注册，以便纳入撤销管理，并在协程结束后考虑将其销毁。

4.3 处理脚本编译依赖

有时 AI 生成的代码片段可能依赖项目中尚未编译的最新更改，或者依赖其他第三方程序集。execute_code会在执行前自动等待编译完成。但如果遇到“类型或命名空间未找到”的错误，可以提示 AI：

1. 检查代码中使用的类名是否完全正确（包括命名空间）。
2. 确认引用的程序集是否已正确导入项目（通过Package Manager或Assets）。
3. 对于复杂的代码，可以尝试将其拆分成更小的、不依赖未编译代码的片段分步执行。

4.4 安全使用的最佳实践

1. 项目备份：在进行大规模的、尤其是涉及资产删除或覆盖的execute_code操作前，确保项目已提交 Git 或进行备份。
2. 善用撤销：教导 AI 在代码中广泛使用ctx.RegisterObjectModification。即使对于通过AssetDatabase修改的资产，虽然不能直接撤销到文件层面，但注册修改有助于在 AI 的思维链中跟踪变更。
3. 限制 AI 权限：在团队环境中，可以通过自定义IFunplayCommand的包装器或前置检查，对 AI 可执行的代码类型进行限制（例如，禁止使用System.IO.File.Delete或Process.Start）。
4. 审查生成的代码：对于重要的、尤其是涉及游戏核心逻辑的修改，不要完全“黑盒”执行。让 AI 先输出代码，你快速浏览一遍再确认执行。Funplay MCP 的get_execute_code_history工具可以帮你回顾历史。

5. 与专用工具的选择：何时用execute_code，何时不用？

execute_code是“万能瑞士军刀”，但并不意味着要抛弃其他 150 个专用工具。正确的策略是混合使用，发挥各自优势。

优先使用execute_code的场景：

• 复杂编排：需要连续调用多个 API 才能完成的复杂任务（如上述创建跑酷场景）。
• 逻辑判断与循环：任务本身包含条件分支、循环迭代（如批量修改资产）。
• 临时性、探索性操作：快速验证一个想法，不需要创建永久脚本文件。
• 访问未暴露的 API：有些 Unity Editor API 可能没有被封装成独立的 MCP 工具，execute_code可以直接调用。
• 运行时热修：在播放模式下动态调整数值、状态或行为。

优先使用专用工具的场景：

• 单一、原子操作：create_primitive（创建立方体）、set_transform（设置位置）、add_component（添加刚体）。这些工具意图明确，AI 调用成本低，结果可预测。
• 需要 AI 清晰理解的操作：像enter_play_mode、capture_game_view这类工具，名称本身就清晰表达了意图，比让 AI 写一段EditorApplication.isPlaying = true的代码更利于理解和规划。
• 资源查询：find_assets、get_scene_info。这些工具返回结构化的资源列表或场景数据，格式稳定，易于 AI 解析。

一个高效的混合模式示例： AI 想要“在场景中心创建一个红色发光的球体，并进入播放模式测试”。

1. 专用工具：create_primitive创建球体。set_transform将其置于 (0,0,0)。create_material创建新材质。assign_material分配材质。set_material_property将颜色调为红色并增加自发光。
2. 专用工具：enter_play_mode。
3. execute_code：编写一小段代码，在播放模式下每帧让球体轻微上下浮动，并检测玩家按下空格键时记录日志。这利用了execute_code处理运行时逻辑和输入检测的优势。
4. 专用工具：capture_game_view截图验证效果。

这种组合既保证了简单操作的效率和清晰度，又用execute_code处理了需要自定义逻辑的部分。

6. 调试与问题排查：当execute_code不工作时

即使设计再精良，在实际使用中也可能遇到问题。以下是常见问题及解决方法。

6.1 连接与基础问题

• 问题：AI 客户端无法调用execute_code，提示连接失败或工具不存在。
  • 检查：确保 Funplay MCP Server 已在 Unity 中通过Funplay > MCP Server启动，并显示Server running on http://127.0.0.1:8765。
  • 检查：确认 AI 客户端（如 Claude Code、Cursor）的 MCP 配置文件中已正确添加funplay服务器配置，端口为8765。
  • 尝试：在 AI 客户端中先尝试调用简单的工具，如get_scene_info，确认基础连接正常。

6.2 代码编译与执行错误

• 问题：execute_code返回编译错误，如CS0246: The type or namespace name '...' could not be found。
  • 解决：首先检查代码中是否有拼写错误。确保使用的类（尤其是自定义类）存在于当前项目中且已编译。可以尝试让 AI 先生成一个不依赖自定义类的简单片段（如Debug.Log("Hello")）来测试。
  • 解决：如果代码依赖刚创建但尚未编译的脚本，需要先调用request_recompile工具，等待编译完成后再执行execute_code。
• 问题：代码执行时抛出运行时异常，如NullReferenceException。
  • 解决：引导 AI 在代码中添加更完善的空值检查和日志。利用ctx.Log输出中间变量状态，帮助定位问题。例如，在查找对象前先ctx.Log($"Searching for objects of type X...")。
  • 解决：检查代码是否在正确的上下文中执行（例如，在非播放模式下尝试访问GameObject.FindWithTag("Player")可能找不到对象）。

6.3 性能与无响应

• 问题：执行execute_code后，Unity 编辑器卡死或无响应。
  • 原因：代码片段中很可能包含无限循环或执行了极其耗时的同步操作（如遍历整个磁盘）。
  • 应对：强制关闭 Unity（任务管理器）。重新打开后，检查execute_code历史，避免再次执行相同代码。
  • 预防：在Funplay > MCP Settings中，可以考虑启用更严格的代码分析（如果未来版本提供），或建立团队规范，禁止 AI 生成包含while (true)或大规模文件遍历的代码。

6.4 撤销与状态管理问题

• 问题：执行execute_code后，按Ctrl+Z无法撤销所有更改。
  • 检查：确认生成的代码正确使用了ctx.RegisterObjectCreation/Modification/DestroyObject来注册所有变更。对于通过new关键字创建但未注册的 UnityEngine.Object，可能无法被撤销栈捕获。
  • 注意：通过AssetDatabase.CreateAsset创建的资产，其创建操作本身可能无法通过标准撤销来回退（尽管文件层面的修改可以）。更安全的做法是在执行批量资产操作前进行项目备份。

6.5 安全守卫误拦截

• 问题：一段看似无害的代码被文件系统守卫拦截。
  • 分析：守卫可能检测到了某些模式，如使用了System.IO.Path.Combine或某些特定的字符串操作。查看返回的错误信息，通常会指明被拦截的原因。
  • 处理：如果确信代码安全，可以在调用execute_code时，通过safety_checks参数（如果 AI 客户端支持）临时禁用或调整安全检查级别。务必谨慎，仅在你完全信任该代码片段和 AI 来源时使用此选项。

execute_code的设计是 Funplay Unity MCP 的灵魂，它模糊了“描述需求”与“实现功能”之间的界限。它要求开发者从“写代码的人”转变为“定义问题和验收结果的人”，而将具体的实现路径交给 AI 去探索和执行。这种范式的转变，才是 AI 赋能游戏开发最深层的价值。开始尝试吧，从一个简单的“创建一些随机分布的树木”开始，你会惊讶于这种流畅的、对话式的开发体验所带来的效率提升和创意释放。