# libpml

**Picture Markup Language** — 一门用于生成游戏 / 动漫风格 sprite 资源的 Lisp-like 声明式编程语言。

> 🌐 [English Version](README.en.md)

[![CI](https://github.com/wvfp/libpml/actions/workflows/ci.yml/badge.svg)](https://github.com/wvfp/libpml/actions)
[![Crates.io](https://img.shields.io/crates/v/pml-llm-api)](https://crates.io/crates/pml-llm-api)
[![docs.rs](https://img.shields.io/docsrs/pml-llm-api)](https://docs.rs/pml-llm-api)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](LICENSE)
[![MSRV](https://img.shields.io/badge/MSRV-1.82-orange)](rust-toolchain.toml)

## PML 是什么？

PML（Picture Markup Language）是一门面向 **sprite 资产生成** 的声明式 / 过程式语言，采用
Lisp 风格的 S-expression 语法。它专为 **LLM 智能体** 设计 —— 让 AI 通过组合参数化的
**语义组件**（角色、物品、UI 控件、场景）来生产游戏 / 动漫资产，而不是像扩散模型那样"画"图。

```pml
(circle 0 0 10 :fill "red")
(anime-eyes :style "shoujo" :color "#4a90d9")
(character :hair "spiky" :eyes "round" :style "cel")
```

PML 解释器解析上述代码，并通过基于 **wgpu** + **Vello** 的 GPU 加速 2D / 3D 渲染管线
输出 PNG / 精灵表，可直接被游戏引擎消费。

## 为什么需要 PML？

传统 LLM 图像生成（扩散模型）有三大痛点：

1. **不可控**：无法精确指定眼睛颜色、服装款式、笔触粗细
2. **难编辑**：修改一个细节必须重新生成
3. **风格不稳定**：两次生成同一角色可能得到不同结果

PML 走另一条路：LLM 不"画"图，而是 **"组装"** 图 —— 通过结构化、参数化的代码。
渲染器保证风格一致，产出引擎可用的资产。

## 快速上手

```bash
# 构建整个工作区
cargo build --workspace

# 启动 REPL
cargo run -p pml-repl

# 运行测试
cargo test --workspace

# 格式化与 Lint
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
```

## 架构

```
libpml (workspace)
├── crates/
│   ├── pml-core          # Span / Symbol / Keyword / Value 等基础类型
│   ├── pml-parser        # Lexer + 递归下降 Parser
│   ├── pml-eval          # 树遍历求值器、环境、内置函数、模块
│   ├── pml-math          # Color / Affine / 插值
│   ├── pml-graphics      # 2D 图元与场景图
│   ├── pml-animation     # 动画、缓动、IK
│   ├── pml-style         # 风格描述符、调色板
│   ├── pml-components    # 语义组件库
│   ├── pml-renderer      # wgpu 2D (Vello) + 3D 延迟渲染
│   ├── pml-io            # PNG / 精灵表 / GIF
│   ├── pml-llm-api       # LLM 友好 API（含 Python / Node.js FFI）
│   └── pml-repl          # 交互式 REPL 二进制
├── stdlib/               # PML 标准库（13 个语义组件）
├── examples/             # 示例 PML 程序
├── eval/                 # LLM 评估任务集（20 个）
└── docs/                 # 设计文档与 mdBook 用户手册
```

## 当前状态

- ✅ **Stage 1** 基础设施：12 个 crate 骨架、CI、lint / fmt 配置
- ✅ **Stage 2** 解析器 + 求值器：Lexer / Parser / AST / 19 个内置函数 / Lambda / Macro
- ✅ **Stage 3** 2D 渲染：Vello 集成、风格描述符、文本渲染
- ✅ **Stage 4** 3D 渲染 + 风格系统：4 种后处理效果、骨骼动画（FABRIK / CCD）、10 个回归场景
- ✅ **Stage 5** 动画 + 组件：12 缓动 / 4 重复模式 / 13 个 stdlib 组件
- 🚧 **Stage 6** LLM API（进行中）：`render_to_png` / `render_to_rgba` / SceneBuilder / FFI 绑定
- 📦 **v0.1.0** 已发布：167+ 测试通过，9 个 Criterion 基准，17 个示例

详见 [CHANGELOG.md](CHANGELOG.md) 与 `.trae/specs/pml-development-plan/` 中的完整开发计划。

## 文档

- [用户手册（mdBook）](docs/src/README.md) — 5 章入门到精通
- [API 参考](https://docs.rs/pml-llm-api) — docs.rs
- `docs/renderer-design.md` — 渲染后端设计
- `rust-architecture.md` — 解释器架构
- `development.md` — 语言规范
- `vello-integration-design.md` — Vello 集成设计

## 贡献

详见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解构建步骤与贡献指南。
参与项目即表示同意遵守 [Code of Conduct](CODE_OF_CONDUCT.md)。

## 许可证

本项目以 **MIT** 或 **Apache-2.0** 双协议发布，任选其一：

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
