• 游戏开发
• 图形学

本篇指南以官方安装文档（docs/source/installing.rst）为主线，系统讲解 Turbulenz SDK 在 Windows、macOS、Linux 三大平台上的前置条件、安装步骤、开发环境激活、本地服务器启动、安装验证与示例运行全流程，并结合开源仓库的 README.rst、manage.py 等源码资源，补充以 Git 方式从源码搭建开发环境的完整途径。读完本文，你将掌握从零开始安装 Turbulenz SDK、快速启动开发环境并通过内置示例验证安装是否成功的方法。

Turbulenz SDK 包含什么

Turbulenz SDK 是开始使用 Turbulenz 引擎的完整工具包，包含以下四类内容：

• 库（Libraries）：引擎核心 JavaScript/TypeScript 库，位于仓库 tslib 目录，涵盖 GraphicsDevice、SoundDevice、NetworkDevice、InputDevice、PhysicsDevice 等底层模块，以及 draw2d.ts、scene.ts 等高层模块；
• 工具（Tools）：用于处理代码与资源的命令行工具，例如dae2json（Collada 转 JSON）、cgfx2json（CgFX 着色器转 JSON）、makehtml、maketzjs等；
• 文档（Documentation）：本仓库 docs 下的全部手册与 API 参考；
• 示例（Examples）：samples 目录下覆盖 2D/3D 渲染、物理、粒子、声音、服务接口等主题的示例，以及 apps 目录下的完整应用（如 multiworm、tictactoe）。

SDK 中同时包含 Turbulenz Engine 开源仓库的全部内容（含预构建示例），以及面向不支持 WebGL 等新特性浏览器/平台的Turbulenz Engine Installer（浏览器插件）。也就是说，开发者既可以通过官方 SDK 安装包获得开箱即用的环境，也可以直接基于 README.rst 从 Git 仓库自行搭建。

技术支持渠道

遇到问题时可参考以下路径：

1. 登录 Turbulenz Hub（官方下载站），点击落地页的Support按钮即可自动进入支持服务；
2. 查阅知识库（knowledge base）或创建支持请求（support request）；
3. 使用支持站点的更多帮助，参见仓库中的 支持文档。

官方文档始终可通过在线地址访问，且支持站点与 SDK 版本保持同步。

安装前的系统要求

在开始安装之前，需要先确认机器满足以下前置条件。无论哪个平台，最核心的一条是：Turbulenz 工具链仅支持 Python 2.7.3 及以上版本（2.7.x 系列），不能使用 Python 3.X。这是仓库源码中硬性校验的约束——manage.py 中command_env的第一条检查就是：

if sys.version_info[1] != 7: error('Turbulenz requires python 2.7') return -1

各平台的具体前置依赖如下。

Windows（XP / Vista / 7）

必需（Essential）

• Python 2.7.3+（官方下载站）。开源仓库 README.rst 进一步建议：Windows 上推荐安装32 位Python；若机器上同时装有多个 Python 版本（例如 3.x），可能需要用python2.7命令显式调用；若安装时未将 Python 加入 PATH，则需使用完整路径C:\Python27\python.exe。

推荐（Recommended）

• Microsoft Visual Studio 2008：用于在平台允许时为 Python 环境编译加速模块（speed-ups）。强烈建议在安装 Turbulenz SDK 之前先装好 VS，这样 speed-ups 才能在环境中正确配置；
• PDF 阅读器：用于阅读 PDF 格式的文档。

⚠️ 注意：如果使用的是 64 位版本的 Python，则必须安装 64 位版本的 Visual Studio 编译器，否则无法编译加速模块。

macOS（OS X 10.7 及以上）

必需（Essential）

• Python 2.7.3+；
• Cg Toolkit（NVIDIA 官方提供）：cgfx2json工具依赖该库来编译着色器；
• Xcode Command Line Tools（2012 年 2 月或更新版本）：如果尚未安装完整 Xcode，仅安装命令行工具即可（下载体积远小于完整 Xcode）；如果已安装 Xcode，可在 Xcode 的 "Downloads" 偏好设置 → "components" 标签页中选择安装 "Command Line Tools"。

Linux（BETA）

Linux 版本 SDK 以自解压 shell 脚本形式发布，已针对 Ubuntu 12.04（64 位）完成测试，同时也欢迎其他较新发行版的使用反馈。需要特别注意的是：

⚠️Linux 版浏览器插件尚未发布，因此 Linux 上运行游戏时必须使用 canvas 模式（即仅依赖浏览器内置的 WebGL 能力）。从源码角度看，starter/getting_started_guide.rst 也明确提示：在 Linux 上构建应用时使用makehtml --mode canvas-debug即可在 Linux 浏览器中运行。

Linux 平台建议通过包管理器安装以下依赖：

必需（Essential）

• Python 2.7.3+（含开发文件）：Linux 下必须安装 Python 开发包（库与头文件）。Ubuntu 上执行：

  sudo apt-get install python-dev

  同时建议从发行版包管理器安装virtualenv与setuptools：

  sudo apt-get install python-virtualenv python-setuptools

• GCC（含 g++）：必须在运行安装脚本之前安装，以便 Python 能够编译某些模块；

• Cg Toolkit 3.0+：SDK 中的cgfx2json工具依赖该库。可以从包管理器安装，也可以前往 NVIDIA 官网下载最新版本，并确保选择与系统匹配的 32/64 位配置。

开源仓库 README.rst 还补充了构建本地工具（cgfx2json、NvTriStrip）时的额外依赖：Linux 需要 GCC 4.6.x 或更高版本，以及 OpenGL 开发库（Debian 系发行版安装libgl1-mesa-dev，例如sudo apt-get install libgl1-mesa-dev）；macOS 需要 Xcode 命令行工具；Windows 可使用 VS2008 SP1、VS2010、VC++ 2010 Express 或 VS2012（含 update 2）等任意一种。

分平台安装步骤

以下安装步骤中，X.X.X为 SDK 版本号占位符，请替换为实际下载的版本号。

Windows 安装

1. 访问官方 Hub 并登录；
2. 下载 Windows 版 SDK（TurbulenzSDK-X.X.X.exe）；
3. 运行TurbulenzSDK-X.X.X.exe；
4. 按安装向导提示完成安装。

Windows 版 SDK 为自解压安装程序（self-extracting installer exe），包含开发 Turbulenz 应用所需的工具、示例和引擎组件。

macOS 安装

1. 访问官方 Hub 并登录；

2. 下载 Mac 版 SDK；

3. 在与 SDK 安装包相同的目录打开终端，依次执行：

   chmod a+x TurbulenzSDK-X.X.X.run ./TurbulenzSDK-X.X.X.run

4. 按安装向导提示完成安装。

Mac 版 SDK 以自解压 shell 脚本（beta）形式提供，同样包含工具、示例和引擎组件。

Linux 安装

1. 访问官方 Hub 并登录；

2. 下载 Linux 版 SDK；

3. 在与 SDK 安装包相同的目录打开终端，依次执行：

   chmod a+x TurbulenzSDK-X.X.X.linux.run ./TurbulenzSDK-X.X.X.linux.run

4. 按安装向导提示完成安装。

从开源仓库搭建（替代方案）

如果不使用官方 SDK 安装包，而是希望直接基于开源代码工作（例如跟进最新版本或参与贡献），README.rst 给出了完整流程：

# 1. 克隆仓库 $ git clone git://github.com/turbulenz/turbulenz_engine.git # 2. 初始化 Git 子模块（external 目录下的 tzbuild、DefinitelyTyped、UglifyJS、NvTriStrip） $ git submodule update --init # 3. 确认已满足前置条件（Python 2.7.x、virtualenv 1.9.1+ 等） # 4. 创建虚拟环境，自动安装所需 Python 包与 NodeJS $ python manage.py env # 5. 激活环境（bash 使用 source，Windows 使用 activate.bat） $ source env/bin/activate # bash 等类 Unix shell > env\scripts\activate.bat # Windows # 6. 由 TypeScript 源码构建 JavaScript 库 $ python manage.py jslib

manage.py 中command_env的实现显示：环境创建会通过virtualenv建立env目录（路径常量ENV = 'env'定义于 scripts/utils.py），并自动easy_install安装simplejson、PyYAML、pylint、roman、docutils、Sphinx、turbulenz_tools、turbulenz_local等依赖包，随后通过 scripts/install_nodejs.py 安装 NodeJS（含 TypeScript 支持）并全局安装tslint。这正好解释了官方文档中"SDK 使用 Python 虚拟环境、避免污染系统默认 Python 目录"的设计初衷。

仓库方式下还可通过manage.py执行更多操作：python manage.py tools（编译 cgfx2json 等本地工具）、python manage.py docs（构建 HTML 文档）、python manage.py samples（构建示例）、python manage.py apps（构建 apps 目录下的应用）。

运行 SDK：激活开发环境

SDK 安装完成后，需要通过"Run the Environment"进入虚拟环境来运行配套工具。

Windows：通过开始菜单快捷方式进入 SDK 虚拟环境命令行：

开始菜单 -> 程序 -> Turbulenz -> SDK X.X.X -> Run Environment X.X.X

说明：该环境启动后的起始目录是 SDK 的安装目录。

macOS / Linux：在终端中执行：

cd *SDKINSTALLDIR* source start_env

激活成功后，命令提示符前会出现(env)标签，此时即可运行 SDK 提供的各种命令行工具。

运行 SDK：启动本地开发服务器

本地开发服务器（Local Development Server）用于在本地机器或局域网内测试你的游戏，同时具备文件服务、Turbulenz 在线服务模拟、指标记录、项目部署等能力（详见 本地服务器用户指南）。

Windows：通过开始菜单中的对应快捷方式启动。

macOS / Linux：在终端中执行：

*SDKINSTALLDIR*/start_local.sh

⚠️防火墙提示：首次运行本地服务器时，部分防火墙可能会弹出提示，询问是否允许python或python.exe监听端口。必须授予权限，服务器才能正常启动运行。

验证安装是否成功

Turbulenz 工具基于 Python 虚拟环境运行，其中安装了全部必需的 Python 包（从而避免了向系统默认 Python 目录安装包）。安装完成后，建议按以下三步验证：

1. 启动本地服务器（操作方式见上一节），确保没有任何报错。Windows 上应看到浏览器自动打开并显示开发服务器首页；

2. 运行 Turbulenz 环境（操作方式见上文）。命令行提示符前出现(env)前缀，即表示环境激活成功；

3. 在环境命令行中测试工具：输入

   dae2json

   应显示dae2json命令的命令行选项说明；如果看到的是错误信息，说明环境没有正确安装。

dae2json是 SDK 中最常用的资源工具之一，负责将 Collada（.dae）模型转换为 Turbulenz 引擎的 JSON 资源格式。根据 工具文档，其语法为：

dae2json [options] -i source.dae -o target.json

典型用法示例：

dae2json -v -m -i assets/models/duck.dae -o apps/sampleapp/models/duck.dae.json

该工具基于 Collada 规范实现，引擎使用Y-up坐标系约定；SDK 0.25.0 起新增--nvtristrip选项，可通过 NvTriStripper 启用顶点缓存优化。仓库 assets/models 下的duck.dae、Seymour.dae、sphere.dae等模型资源均可用于测试该工具。

运行示例验证全流程

本地开发服务器运行后，即可通过浏览器体验内置示例：

1. 打开浏览器，访问http://127.0.0.1:8070；
2. 点击Samples项目，再点击Play按钮，显示可用示例列表；
3. 每个示例对应多个 HTML 文件，分别代表不同的构建配置（如 canvas-debug、canvas release 等）；
4. 点击某个 HTML 文件名即可打开并运行对应示例。

关于构建配置，starter/getting_started_guide.rst 解释了三种主要模式：

• plugin：使用浏览器扩展插件提供底层能力，代码打包为单个.tzjs文件，适合发布部署；
• canvas：不使用插件，仅依赖浏览器内置能力，代码打包为单个.js文件；
• canvas-debug：面向开发调试，代码几乎不做转换，可直接用浏览器开发者工具调试，也是 Linux 平台唯一可用的运行模式。

示例源码位于 samples/tsscripts/templates，例如 2D 渲染的 draw2d.ts、3D 渲染的 camera.ts、物理的 physics.ts 等，它们由 TypeScript 编写，构建后生成对应的 HTML 页面。

平台与浏览器支持情况

需要特别注意的是，官方安装文档中"运行 SDK"一节引用了系统要求章节（对应 支持的平台与浏览器文档）。对最终玩家而言，支持的平台组合为：

• Windows（32/64 位）XP / Vista / 7 / 8：IE 8/9/10、Firefox 3.6+、Chrome；
• macOS 10.7+：Safari 6+、Firefox、Chrome；
• Linux（仅 WebGL 支持）：Firefox、Chrome；
• Android：Chrome Beta、Firefox Beta。

对开发者而言，除上述组合外，还提供面向 Android 与 iOS 的 Turbulenz Developer Client，详情参见 developer_client_readme.rst。这些信息可用于判断目标机器与浏览器是否符合运行 SDK 及所开发游戏的软硬件要求。

安装后的下一步

安装与验证完成后，官方推荐继续阅读 入门指南（Getting Started Guide），它从最简单的"清屏"示例出发，逐步讲解如何编写、构建并运行第一个 Turbulenz 应用（包括makehtml、maketzjs的完整用法），并介绍 Turbulenz 应用的基本概念（入口点TurbulenzEngine.onload、主循环TurbulenzEngine.setInterval、构建模式等）。遇到问题时，可参照 支持文档 中的文档、讨论组与开源贡献渠道；发行说明则位于 release_notes，可据此了解各 SDK 版本间的变更与升级信息。

• 游戏开发
• 图形学