跳转到主要内容
blockscope 的构建和路径说明见 安装与快速开始。

​
命令总览

​
常用示例

多视角渲染时，单视角输出 out.png，多视角输出 out-45.png、out-225.png 等。serve 模式的输出命名为 {id}.png（单视角）或 {id}-{yaw}.png（多视角）。有完整 mesh 时，多视角会按 --threads 预算并行渲染；输出顺序不变，并且每个视角会在下一批开始前写出并释放缓冲，内存不会随视角数量无限增长。 终端图像会先适配可见网格：渲染尺寸超过窗口时只向终端指定一个字符维度，由终端按原始宽高比缩小图像。摘要先输出、图像最后输出，后续文字不会把它顶出屏幕。在 tmux 或 screen 内（默认会丢弃图形序列，除非开启 passthrough），自动检测会退化为半块字符；需要时用 --terminal-protocol 覆盖。当 stdout 不是终端（管道、日志、被捕获的 shell）时会给出警告，因为转义序列无法显示。

​
常用选项

inspect、validate 和 stats 默认保留 TileEntities 内容；几何命令默认跳过，以减少大容器文件的解析时间和内存。 GPU 后端需要完整 Mesh，不能与 --stream-mesh on 同用。若二进制未启用 gpu 特性或没有可用硬件适配器，显式 gpu 会以 BACKEND_UNAVAILABLE 失败；auto 则回退到 CPU。GPU 输出与 CPU 参考视觉接近，但跨驱动不保证逐字节一致，因此 golden PNG 和确定性保证仍以 cpu 为准。

​
终端样式与进度

在没有参数时，blockscope 打印静态欢迎屏并立即退出。字标会按启动时的终端宽度和高度选择布局；输出被重定向时使用紧凑字标。静态输出退出后由终端负责重排，程序无法继续控制已经打印的字符。 字标会按终端宽度和高度逐级降级：82 列宽字标、59 列紧凑字标、47 列小字标，更窄时改用纯文字标题并只保留最有用的命令；输出被重定向时使用紧凑字标。 --color 可放在子命令前后，控制帮助、错误和人类可读结果的颜色： --json 输出始终是纯 JSON，不受 --color 影响。 render、bench、mesh 和 materials 在 stderr 是终端时显示进度：解析、材质、网格页数和单视角栅格化的 tile 百分比。多视角显示视角计数；流式渲染的最终合成使用不定进度。以下情况自动关闭：stderr 不是终端、--json、设置了 CI 环境变量、NO_COLOR，或 --color never。进度只写入 stderr，不会影响 stdout 和管道输出；进度条会按终端宽度缩短或改为只显示计数，窗口缩放后会自动重排。

​
退出码

  • 0：成功
  • 1：内部错误
  • 2：输入无效、解析失败或资源超限

​
相关文档