npm package: @netwan/lava
Description: LavaX C compiler and virtual machine - An embedded C language compilation system for compiling and running .lav bytecode
Author: netwan
Latest version: 1.0.8

# LavaX 编译器与虚拟机

LavaX 是一个嵌入式 C 语言编译器和虚拟机系统，用于编译和运行 .lav 格式的 LavaX 程序。

## What's New

### 结构体支持增强

- **结构体指针成员访问** - 支持通过指针访问结构体成员 (`ptr->member`)
- **结构体函数传参** - 支持结构体作为函数参数传递
- **结构体赋值** - 支持结构体之间的直接赋值
- **typedef for struct** - 支持结构体类型别名定义

### 变量系统改进

- **变量遮蔽** - 支持局部变量遮蔽全局变量，并区分不同类型的警告
- **char array pointer** - 字符数组指针支持
- **extern 声明** - 外部变量声明支持
- **带注释的宏定义** - 宏定义中支持注释处理

### 函数指针

- **变量索引函数指针调用** - 支持通过变量索引调用函数指针
- **函数指针数组** - 支持函数指针数组的常量索引调用

### 编译器增强

- **debug_verbose 模式** - 使用 `-v` 参数控制调试输出详细程度
- **常量索引优化** - 编译期常量索引优化
- **彩色错误输出** - 错误信息支持彩色高亮显示

### 新增工具

- **ldc** - 字节码反编译器，可将 `.lav` 文件还原为可读指令清单
  ```bash
  ldc program.lav              # 查看字节码
  ldc program.lav --pseudo-c   # 生成伪C代码
  ```

### 虚拟机改进

- **lvm1** - SDL1 版虚拟机，支持控制台 stdout/stdin，适合调试和 AI 交互
- **lvm2** - SDL2 版虚拟机，纯 GUI 模式，无控制台窗口
- **verbose 模式** - 虚拟机支持详细调试输出

### 构建系统

- **configure 脚本** - 自动检测依赖并生成配置文件
- **跨平台支持** - 同时支持 Windows (MinGW) 和 Linux 环境
- **Windows 兼容性** - 修复临时文件路径等 Windows 特定问题

---

## 平台支持

| 平台 | 架构 | 状态 |
|------|------|------|
| Linux | x64 | ✅ 支持 |
| Linux | arm64 | ✅ 支持 |
| Windows | x64 | ✅ 支持 |

## 安装

```bash
npm install -g @adouming/lava
```

安装后，以下命令将可用：
- `lc` - LavaX 编译器
- `lvm1` - SDL1 版虚拟机
- `lvm2` - SDL2 版虚拟机
- `lpp` - 预处理器

## 项目组成

- **lc** - LavaX 编译器，将 C 源码编译为 .lav 字节码
- **lpp** - LPP 预处理器（基于 tinycc 移植）
- **lvm2** - SDL2 版 LavaX 虚拟机（基于sdl2，纯gui，无控制台）
- **lvm1** - SDL1 版 LavaX 虚拟机（基于sdl1，兼容cli模式，终端有stdout和stdin）

## lc 编译器新功能

### 语法新特性

| 特性 | 说明 |
|------|------|
| `typedef` | 支持 typedef 类型定义 |
| `enum` | 支持枚举类型 |
| `#encoding utf8` | 支持 UTF-8 编码的源代码 |
| 局部变量任意位置定义 | 使用 `-a` 参数允许在代码任意位置定义局部变量 |
| 变参函数 | 支持可变参数函数 |
| 复杂宏定义 | 支持复杂宏定义 |
| `switch` 语句 | 支持 switch 分支语句 |
| 三目运算 | 支持 A ? B : C 三目运算符 |
| 彩色错误输出 | 支持彩色错误输出 |
| yield 语句 | 生成式函数指令，编译期协程支持 |
| 跨平台支持 | 同时支持win和linux 环境 |


### 预处理器

- **LPP 预处理器**：基于 tinycc 预处理器移植，替代 GNU cpp
- 支持 LavaX 特殊指令：`#width`, `#height`, `#color`, `#pen`, `#autoscreen`, `#watch`, `#secret`, `#loadall`, `#bigram`, `#encoding`

### 编译器功能

- **调试模式**：使用 `-v` 参数显示详细调试信息

```

## 使用方法（npm 安装后）

### lc 编译器

```bash
# 基本编译
lc source.c -o output.lav

# 允许任意位置定义局部变量
lc source.c -o output.lav -a

# 显示调试信息
lc source.c -o output.lav -v

# 显示帮助
lc --help
```

### lvm2 虚拟机（图形模式）

```bash
# 打开指定的 .lav 文件
lvm2 game.lav

# 打开目录（自动查找第一个 .lav 文件）
lvm2 /path/to/games/

# 不带参数（暂时不支持 Shell）
lvm2

# 显示帮助
lvm2 --help
```

### lvm1 虚拟机（主要用于控制台模式debug，和AI交互）

```bash
# 运行 .lav 文件
lvm1 game.lav

# 显示帮助
lvm1 --help
```

### lpp 预处理器

```bash
# 预处理 C 源码
lpp source.c -o output.i
```

## 键盘控制映射

| 游戏按键 | 键盘按键 |
|---------|---------|
| **方向键** ||
| ↑ | ↑ (Up Arrow) |
| ↓ | ↓ (Down Arrow) |
| ← | ← (Left Arrow) |
| → | → (Right Arrow) |
| **游戏按钮** ||
| A | `L` 或 `Space` |
| B | `K` 或 `Left Ctrl` |
| X | `P` 或 `Left Shift` |
| Y | `O` 或 `Left Alt` |
| **肩键** ||
| L1 | `Tab` 或 `PageUp` |
| R1 | `Backspace` 或 `PageDown` |
| **系统按键** ||
| Select | `5` 或 `Right Ctrl` |
| Start | `6` 或 `Enter` |
| **特殊功能** ||
| 退出当前程序 | `Enter` (单独按下) 或 `ESC` |
| 退出虚拟机 | `Select` + `Start` 同时按下 |
| 切换网格显示 | `R1` + `Select` |
| 切换FPS显示 | `L1` + `Select` |

## 手柄支持

程序支持标准游戏手柄，按键映射会根据手柄类型自动适配（Xbox 布局或标准布局）。

## 显示模式

- **桌面分辨率 > 1024x600**：使用 640x480 窗口模式
- **桌面分辨率 ≤ 1024x600**：使用全屏模式

## 目录结构

```
LavaXOS/
├── System/
│   ├── ShellX.sys    # 默认 Shell 程序
│   └── Config.ini    # 配置文件
└── ...
```

## 许可证

（待补充）