> ## Documentation Index
> Fetch the complete documentation index at: https://blockscope.linvin.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

# 安装与快速开始

## 系统要求

* Windows x86\_64、Linux x86\_64 或 Linux aarch64
* 使用预编译二进制时不需要 Rust 工具链
* 从源码构建时需要 Rust stable（支持 edition 2024；建议 Rust 1.85 或更新）
* 可选：Minecraft 客户端 jar、已解压的 `assets/` 目录或资源包
* 可选：Docker（用于容器部署）
* 常规 1024x1024 预览建议至少 1 GiB 内存；开启超采样、提高尺寸或渲染超大
  结构时需要更多内存

## 下载预编译二进制（推荐）

在 [Releases](https://github.com/Linvin-1233/Blockscope/releases) 下载对应平台的
安装包或压缩包：

| 平台 | 目标三元组 | 格式 |
| - | - | - |
| Linux x86\_64 | `x86_64-unknown-linux-musl` | `.tar.gz` |
| Linux aarch64 | `aarch64-unknown-linux-musl` | `.tar.gz` |
| Windows x86\_64 | `x86_64-pc-windows-msvc` | `.msi` / `.zip` |
| macOS aarch64 | `aarch64-apple-darwin` | `.tar.gz` |
| macOS x86\_64 | `x86_64-apple-darwin` | `.tar.gz` |

文件名形如 `blockscope-v0.2.0-x86_64-unknown-linux-musl.tar.gz`，旁边有去掉扩展名
的 `.sha256` 校验文件（如 `blockscope-v0.2.0-x86_64-unknown-linux-musl.sha256`）。
Linux 产物静态链接 musl，Windows 产物静态链接 CRT，目标机器不需要额外安装运行时库。

### Linux

```bash theme={null}
curl -LO https://github.com/Linvin-1233/Blockscope/releases/download/v0.2.0/blockscope-v0.2.0-x86_64-unknown-linux-musl.tar.gz
curl -LO https://github.com/Linvin-1233/Blockscope/releases/download/v0.2.0/blockscope-v0.2.0-x86_64-unknown-linux-musl.sha256
sha256sum -c blockscope-v0.2.0-x86_64-unknown-linux-musl.sha256
tar -xzf blockscope-v0.2.0-x86_64-unknown-linux-musl.tar.gz
./blockscope-v0.2.0-x86_64-unknown-linux-musl/blockscope --version
```

### macOS

Apple Silicon（M 系列）选择 `aarch64-apple-darwin`，Intel Mac 选择 `x86_64-apple-darwin`：

```bash theme={null}
curl -LO https://github.com/Linvin-1233/Blockscope/releases/download/v0.2.0/blockscope-v0.2.0-aarch64-apple-darwin.tar.gz
curl -LO https://github.com/Linvin-1233/Blockscope/releases/download/v0.2.0/blockscope-v0.2.0-aarch64-apple-darwin.sha256
shasum -a 256 -c blockscope-v0.2.0-aarch64-apple-darwin.sha256
tar -xzf blockscope-v0.2.0-aarch64-apple-darwin.tar.gz
./blockscope-v0.2.0-aarch64-apple-darwin/blockscope --version
```

### Windows：MSI 安装（推荐）

按用户安装，不需要管理员权限：

```powershell theme={null}
$tag = "v0.2.0"
$name = "blockscope-$tag-x86_64-pc-windows-msvc"
Invoke-WebRequest "https://github.com/Linvin-1233/Blockscope/releases/download/$tag/$name.msi" -OutFile "$name.msi"
Invoke-WebRequest "https://github.com/Linvin-1233/Blockscope/releases/download/$tag/$name.msi.sha256" -OutFile "$name.msi.sha256"
Get-FileHash "$name.msi" -Algorithm SHA256
Get-Content "$name.msi.sha256"
msiexec /i "$name.msi"
```

安装到 `%LOCALAPPDATA%\Programs\Blockscope`，并把该目录追加到当前用户的 `PATH`；
重新打开终端后 `blockscope --version` 即可用。卸载在“设置 → 应用”里，卸载会同时
移除 `PATH` 条目。静默安装用 `msiexec /i "$name.msi" /qn`。

### Windows：便携 zip

不想安装时直接解压：

```powershell theme={null}
$tag = "v0.2.0"
$name = "blockscope-$tag-x86_64-pc-windows-msvc"
Invoke-WebRequest "https://github.com/Linvin-1233/Blockscope/releases/download/$tag/$name.zip" -OutFile "$name.zip"
Invoke-WebRequest "https://github.com/Linvin-1233/Blockscope/releases/download/$tag/$name.sha256" -OutFile "$name.sha256"
Get-FileHash "$name.zip" -Algorithm SHA256
Get-Content "$name.sha256"
Expand-Archive "$name.zip" -DestinationPath .
.\$name\blockscope.exe --version
```

`Get-FileHash` 输出的哈希应与 `.sha256` 文件中的值一致。把解压目录加入 `PATH`，
下文命令中的 `blockscope` 均指该可执行文件。

## 从源码构建

需要 Rust stable。用于开发、审查或自行修改引擎：

```bash theme={null}
git clone https://github.com/Linvin-1233/Blockscope.git
cd Blockscope
cargo build --release -p blockscope-cli
```

构建产物：

* Linux：`target/release/blockscope`
* Windows：`target/release/blockscope.exe`

可以把 `target/release` 加入 `PATH`，也可以在命令中直接使用完整路径。

## 运行测试

```bash theme={null}
cargo test --workspace
```

## 第一次渲染

没有资源包时使用内置色块：

```bash theme={null}
blockscope inspect model.litematic --json
blockscope validate model.litematic
blockscope render model.litematic --output out.png
```

使用 Minecraft 客户端 jar 获得真实材质：

```powershell theme={null}
blockscope render model.litematic `
  --output out.png `
  --client-jar "C:\path\to\client.jar"
```

```bash theme={null}
blockscope render model.litematic \
  --output out.png \
  --client-jar /path/to/client.jar
```

也可以使用已解压的 assets 目录：

```bash theme={null}
blockscope render model.litematic --output out.png --assets /path/to/assets
```

## 下一步

* [CLI 命令](https://blockscope.linvin.net/user/cli.md)
* [材质与资源包](https://blockscope.linvin.net/user/materials.md)
* [LOD 与大结构](https://blockscope.linvin.net/user/lod.md)
* [故障排查](https://blockscope.linvin.net/user/troubleshooting.md)
* [English](https://blockscope.linvin.net/user/en/getting-started.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.