# rust-zw3d

**Repository Path**: rust-cad/rust-zw3d

## Basic Information

- **Project Name**: rust-zw3d
- **Description**: rust 与zw3d 桥接，使用rust进行zw3d二开
- **Primary Language**: Rust
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-10
- **Last Updated**: 2025-12-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

rust-zw3d
==========

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/rust-1.90%2B-orange.svg)](https://www.rust-lang.org/)
[![ZW3D](https://img.shields.io/badge/ZW3D-24%7C25%7C26-blue.svg)](https://www.zwsoft.cn/)

当前版本：**Alpha**（框架阶段）。仅提供基础绑定与最小封装，仍需进一步打磨与扩展，欢迎 Issue/PR。

Rust 版 ZW3D SDK 绑定与工具集。

## 特性

- ✅ 提供由 bindgen 生成的低层 FFI 绑定（`rust-zw3d-raw`）
- ✅ 提供 Rust 风格的高层封装（`rust-zw3d::editor` 等模块）
- ✅ 提供命令与回调的注册/卸载工具，以及模块进出点宏
- ✅ 通过 `zw3d.toml` 指定 SDK 主版本与路径
- ✅ **完整的中文支持**（自动 GBK ↔ UTF-8 转换）
- ✅ **类型安全**的宏，支持多种函数签名
- ✅ **零配置**，开箱即用

## 快速链接

- 📦 [快速上手](#快速上手)
- 📚 [文档](#文档)
- 🔧 [开发环境设置](#环境准备与链接)
- 💡 [示例工程](#示例工程)

工作区结构
-----------

- `crates/rust-zw3d`：核心 crate，提供 Rust 风格的封装:
  - `editor`：编辑器交互封装（如 `msg_disp`、`get_angle`、`get_string`）
  - `commands`：命令/回调注册封装
  - `raw`：重导出 `rust-zw3d-raw`，可通过 `rust_zw3d::raw` 访问原始 FFI
  - 宏与注册工具：`register_commands!`、`register_callbacks!`、`zw3d_module!` 等
- `crates/rust-zw3d-raw`：原始 FFI 绑定 crate，由 bindgen 自动生成
- `crates/rust-zw3d-macros`：过程宏 crate，导出属性宏 `#[cmd]`、`#[callback]`
- `crates/rust-zw3d-build`：构建工具 crate，用于解析 SDK 配置

环境准备与链接
--------------

通过 `zw3d.toml` 告诉构建脚本如何查找 SDK：

1) 在 `~/.zw3d/zw3d.toml` 创建配置（或在项目内复制 `zw3d.toml.example`）：

```toml
[zw3d]
# 支持 ${ENV_VAR} 格式的占位符
path = "${ZW3D_DIR}"          # 包含 ZW3D.lib 的目录
include = "${ZW3D_INCLUDE}"   # 可选，默认为 ${ZW3D_DIR}/api/inc
version = "${ZW3D_VERSION}"   # 可选，未设置时默认 26
```

2) 如果需要使用自定义位置，可设置环境变量（构建脚本在缺省文件时也会直接读取）：

```powershell
$env:ZW3D_TOML = "D:\\configs\\zw3d.toml"
```

构建脚本会加载配置、校验 `ZW3D.lib` 与头文件路径，并在缺失时直接报错。
若未提供 `zw3d.toml`，则自动读取环境变量：
- `ZW3D_DIR`（必填）：包含 `ZW3D.lib` 的目录
- `ZW3D_INCLUDE`（可选）：头文件目录，默认为 `${ZW3D_DIR}/api/inc`
- `ZW3D_VERSION`（可选）：SDK 版本号，默认为 26
如需在 CI / 发布阶段跳过真实 SDK，可设置 `RUST_ZW3D_ALLOW_STUB=1`，构建脚本会回退到仓库内的默认绑定（仅适用于打包/验证）。

> 插件或示例工程可在 `build.rs` 中复用 `rust-zw3d-build`：

```toml
[build-dependencies]
rust-zw3d-build = "0.1.0-alpha.7"
```

```rust
fn main() {
    println!("cargo:rerun-if-env-changed=ZW3D_TOML");
    println!("cargo:rerun-if-env-changed=ZW3D_DIR");
    println!("cargo:rerun-if-env-changed=ZW3D_INCLUDE");
    println!("cargo:rerun-if-env-changed=ZW3D_VERSION");
    let sdk = rust_zw3d_build::ensure_sdk();
    println!("cargo:rustc-link-search=native={}", sdk.lib_dir.display());
    println!("cargo:rustc-link-lib=ZW3D");
    if let Some(path) = &sdk.config_path {
        println!("cargo:rerun-if-changed={}", path.display());
    }
}
```

SDK 版本
--------

- `zw3d.version` 会写入编译期常量 `rust_zw3d::SDK_VERSION`
- 旧版的 `24/25/26` feature 已移除，版本选择完全由配置文件决定
- `macros` feature 仍然可用于关闭宏重导出（默认开启）

快速上手
--------

在你的插件 crate 中：

```toml
[dependencies]
rust-zw3d = "0.1.0-alpha.7"
```

```rust
use rust_zw3d::{*, editor};

#[cmd] // 可选参数：#[cmd("Alias")] 或 #[cmd(name = "Alias", code = raw::VX_CODE_GENERAL)]
fn hello(_code: i32) -> i32 {
    editor::msg_disp("hello from rust");
    0
}

#[callback] // 可选：#[callback("OnEvent")] 指定回调名
fn on_event(name: &str, a: i32, b: i32) -> i32 {
    editor::msg_disp(name);
    0
}

// 生成模块的 Init/Exit 出口：进入时注册命令/回调，退出时卸载
// 基本用法
zw3d_module!(myplugin);

// 或带自定义初始化/退出函数
fn my_init() -> i32 {
    editor::msg_disp("插件已加载！");
    0
}

fn my_exit() -> i32 {
    editor::msg_disp("插件已卸载！");
    0
}

zw3d_module!(myplugin, init: my_init, exit: my_exit);
```

示例工程
--------

参见 `samples/hello`，展示了最小可用的命令与回调。

如果希望体验从 crates.io 获取依赖的场景，可查看 `samples/hello-simple`，其通过 `[patch.crates-io]` 在仓库内覆盖到本地源码，方便开发调试。

```rust
// samples/hello/src/lib.rs
use rust_zw3d::{*, editor};

// 支持多种函数签名
#[cmd]
fn test_no_params() -> i32 {
    editor::msg_disp("测试：无参数");  // ✅ 自动支持中文
    0
}

#[cmd]
fn test_str(name: &str) -> i32 {
    editor::msg_disp(&format!("你好，{}！", name));  // ✅ 接收和输出都支持中文
    0
}

#[cmd]
fn test_two_i32(a: i32, b: i32) -> i32 {
    editor::msg_disp(&format!("计算：{} + {} = {}", a, b, a + b));
    a + b
}

#[callback]
fn on_event(name: &str, field_id: i32, data_id: i32) -> i32 {
    editor::msg_disp(&format!("事件：{}", name));
    0
}

zw3d_module!(hello);
```

## 文档

### 用户文档

- 📖 **[中文支持指南](docs/中文支持.md)** - 如何在插件中使用中文
  - 自动编码转换
  - 使用示例
  - 常见问题

- ⚙️ **[模块初始化指南](docs/模块初始化.md)** - 自定义初始化和退出逻辑
  - 模块生命周期
  - 使用方法
  - 最佳实践

- 🐛 **[调试指南](docs/调试指南.md)** - 如何调试 ZW3D 插件
  - VSCode 配置
  - 断点调试
  - 常见问题解决

### 开发者文档

- 🔧 **[VSCode 调试配置](.vscode/DEBUG_GUIDE.md)** - 详细的 VSCode 调试说明
- 🚀 **[快速设置指南](.vscode/SETUP.md)** - VSCode 扩展安装和配置

### API 文档

- 📦 **[rust-zw3d crate](crates/rust-zw3d/README.md)** - 核心 crate 文档
- 🎯 **[rust-zw3d-macros crate](crates/rust-zw3d-macros/README.md)** - 宏 crate 文档

## 功能特性

### 自动中文支持

rust-zw3d 自动处理中文编码转换，无需任何配置：

```rust
use rust_zw3d::editor;

#[cmd]
fn greet(name: &str) -> i32 {
    editor::msg_disp(&format!("欢迎，{}！", name));  // ✅ 完美支持中文
    0
}
```

详见 [中文支持指南](docs/中文支持.md)。

### 灵活的函数签名

宏支持多种参数组合：

```rust
// 无参数
#[cmd]
fn cmd1() -> i32 { 0 }

// i32 参数
#[cmd]
fn cmd2(code: i32) -> i32 { code }

// 字符串参数
#[cmd]
fn cmd3(name: &str) -> i32 { 0 }

// 混合参数
#[cmd]
fn cmd4(name: &str, a: i32, b: i32) -> i32 { a + b }

// 无返回值
#[cmd]
fn cmd5(code: i32) {
    editor::msg_disp(&format!("Code: {}", code));
}
```

### UI 资源构建

rust-zw3d 自动支持 UI 资源构建：

1. 在项目根目录创建 `ui/` 文件夹，并将 `.ui` 文件放入其中
2. 在 `build.rs` 中调用 `rust_zw3d_build::build_ui_resources(&sdk_config)`
3. 构建时会自动调用 ZW3D SDK 的 `zrc.exe` 工具编译 UI 资源
4. 生成的 `.zrc` 文件会自动放入 `target/debug` 或 `target/release` 目录

```rust
// build.rs
fn main() {
    let sdk_config = rust_zw3d_build::ensure_sdk();
    
    // 检查并构建 UI 资源
    match rust_zw3d_build::build_ui_resources(&sdk_config) {
        Ok(_) => println!("UI 资源构建完成（如果存在的话）"),
        Err(e) => println!("警告：UI 资源构建失败: {}"),
    }
    
    // ... 其他构建代码
}
```

构建完成后，生成的 `.zrc` 文件会与可执行文件放在同一目录下，便于加载使用。

### 类型安全

编译时检查函数签名，避免运行时错误：

```rust
#[cmd]
fn invalid(x: f64) -> i32 {  // ❌ 编译错误：不支持 f64
    0
}
```

## 项目结构

```
rust-zw3d/
├── crates/
│   ├── rust-zw3d/          # 核心 crate（Rust 风格封装）
│   ├── rust-zw3d-raw/      # 原始 FFI 绑定
│   ├── rust-zw3d-macros/   # 过程宏 crate
│   └── rust-zw3d-build/    # 构建工具 crate
├── samples/
│   ├── hello/              # 完整示例插件
│   └── hello-simple/       # 简化示例插件
├── docs/                   # 用户文档
│   ├── 中文支持.md
│   └── 调试指南.md
├── .vscode/                # VSCode 配置
│   ├── launch.json         # 调试配置
│   ├── tasks.json          # 构建任务
│   └── *.md                # VSCode 相关文档
└── zw3dsdk/                # ZW3D SDK（需要手动配置）
    ├── inc/                # 头文件
    └── lib/                # 库文件
```

## 常见问题

### Q: 如何处理中文字符串？

**A:** rust-zw3d 自动处理中文编码转换，直接使用 Rust 字符串即可。详见 [中文支持指南](docs/中文支持.md)。

### Q: 如何调试插件？

**A:** 使用 VSCode + CodeLLDB 扩展。详见 [调试指南](docs/调试指南.md)。

### Q: 支持哪些 ZW3D 版本？

**A:** 在 `zw3d.toml` 中配置 `[zw3d]` 的 `version`（如 `"24"`/`"25"`/`"26"`）。

### Q: 如何贡献代码？

**A:** 欢迎提交 Issue 和 Pull Request：
- 仓库：https://gitee.com/rust-cad/rust-zw3d
- 讨论：通过 Issue 讨论新功能或改进建议

## 路线图

- [x] 基础 FFI 绑定
- [x] 命令和回调宏
- [x] 中文支持（GBK 编码转换）
- [x] 多种函数签名支持
- [x] 模块初始化和退出函数
- [x] VSCode 调试配置
- [ ] 更多 API 封装
- [ ] 完善文档和示例
- [ ] 单元测试和集成测试
- [ ] 发布到 crates.io

## 发布到 crates.io（计划中）

- 在各 crate 的 `Cargo.toml` 中补充元数据
- 确保不携带专有 SDK
- 通过 `.gitignore` 与 Cargo 包含/排除规则避免将 `zw3dsdk` 打包

## 贡献

欢迎贡献！请查看：
- [Issue](https://gitee.com/rust-cad/rust-zw3d/issues) - 报告问题或建议
- [Pull Request](https://gitee.com/rust-cad/rust-zw3d/pulls) - 提交代码

## 许可

MIT License - 详见 [LICENSE](LICENSE) 文件

## 致谢

- [ZW3D](https://www.zwsoft.cn/) - 提供 SDK
- [bindgen](https://github.com/rust-lang/rust-bindgen) - FFI 绑定生成
- [encoding_rs](https://github.com/hsivonen/encoding_rs) - 编码转换
- Rust 社区

---

**仓库**: https://gitee.com/rust-cad/rust-zw3d  
**文档**: [docs/](docs/)  
**示例**: [samples/hello](samples/hello)