CLI

本页面为自动翻译，可能包含错误。如果发现问题，请通过“编辑此页面”链接帮助修正。

turian-cli 是Turian Studio的无头伴侣。它可以搭建项目、打印元数据并编译自包含的游戏可执行文件——无需GUI，因此非常适合持续集成。

命令

new-project

turian-cli new-project <path> "<Display Name>"

搭建一个新的项目目录，包含 assets/ 文件夹和一个初始场景。

turian-cli new-project ../my-game "My Game"

info

turian-cli info <path>

打印项目的元数据（名称、版本、资源数量）。

build

turian-cli build <path>

将每个资源烹饪到 <path>/.cache/game.oap，生成 build.zig + main.zig，并在 <path>/.cache/zig-out/bin/game[.exe] 编译出独立可执行文件。

生成的二进制文件是自包含的：它从同级的 game.oap 读取所有资源，无需引擎源码树即可运行。

package

turian-cli package <subcommand> [--project <path>] [args]

管理项目的包。除非指定 --project，否则操作当前目录。

子命令 描述
install <source> 从本地路径或git URL安装包
remove <name> 按清单名称移除已安装的包
update [name] 更新一个（或所有）包——git源会重新安装
list 列出已安装的包（名称、版本、类型）
info <name> 打印包的完整清单
search <query> 搜索注册表（尚不可用——在注册表工作中跟踪）

请参阅包指南了解完整工作流程。

从源码检出构建

如果您在引擎仓库内工作而非使用SDK捆绑包：

zig build cli -- build path/to/my-project

路径解析

turian-cli 按以下优先级查找引擎源码：

  1. 环境变量 — 例如 TURIAN_ENGINE_ROOT（最高优先级）。
  2. SDK相对路径 — 从二进制文件旁边的 turian-sdk.json 标记文件解析。
  3. 构建时烘焙路径 — 仅存在于树内开发构建中。

参见环境变量覆盖获取完整列表。

debug

turian-cli debug <subcommand> [--host 127.0.0.1] [--port 7777] [--token <secret>]

连接到正在运行的游戏调试服务器并发送JSON-RPC查询。要求游戏已链接 debug 模块并启动服务器。

子命令 描述
connect Ping服务器（健康检查）
scenes 列出已加载的场景
inspect <name> 按名称检查实体
entities 列出活动场景中的所有实体
component <entity> <comp> 读取组件的字段
snapshot 完整场景快照
schema 内置组件类型目录

参见远程调试协议参考文档获取完整方法列表。

docs

turian-cli docs export-ai-context [--out <dir>]

生成自包含的AI知识包，无需运行游戏。所有输出均来自编译时引擎数据。

标志 默认值 描述
--out .turian/ 输出目录

输出文件：

文件 内容
engine-overview.md 架构、关键概念、快速连接指南
component-schema.json 所有内置组件类型及其字段定义
mcp-tools.json MCP工具目录，包含输入模式和调试方法映射
protocol-reference.json JSON-RPC方法列表，含参数和错误码
examples/list-scenes.json 示例请求/响应对
examples/inspect-entity.json 示例请求/响应对

添加到 CLAUDE.md 以给Claude Code提供离线上下文：

@.turian/engine-overview.md

参见MCP集成指南了解实时连接设置。

mcp

turian-cli mcp [--host 127.0.0.1] [--port 7777] [--token <secret>]

启动一个由运行中的游戏调试服务器支持的MCP服务器（stdio传输，MCP 2024-11-05）。设计为由Claude Code或Cursor作为MCP子进程启动。

参见MCP集成指南了解设置说明。

在CI中使用

由于 build 是完全无头的，典型的流水线步骤就是：

build-game:
  script:
    - turian-cli build .
  artifacts:
    paths:
      - .cache/zig-out/bin/

← 所有文档 编辑此页面