eggpy

一个将蛋仔地图 Lua 与 Python 互转的工具。

目录

• eggpy
  • 目录
  • 介绍
  • 特性
  • 安装
  • 使用方法
    • 初始化项目
    • 编写 Python 文件
    • 反向转换
  • 命令行参数
    • init 命令
    • reverse 命令
  • 原理
  • API 文档
    • 数据类型
    • 数学库
    • 向量与四元数
    • 字典类型
  • 环境限制
  • 开发指南
    • 项目结构
    • 模块拆分
    • 第三方库隔离
  • 贡献
  • 许可证

介绍

eggpy 是一个专门为蛋仔地图开发设计的工具，用于在 Lua 和 Python 之间进行双向转换。蛋仔游戏运行在安全沙盒中，对 Lua 环境有特殊限制，本工具帮助开发者使用 Python 编写游戏逻辑，然后转换为兼容的 Lua 代码。

特性

• 双向转换: 支持 Lua → Python 和 Python → Lua 双向转换
• API 生成: 自动从 EggyAPI.lua 生成对应的 Python API 定义
• 模块化设计: 将庞大的 EggyAPI.lua 拆分为功能模块
• 环境兼容: 生成的代码严格遵守蛋仔游戏沙盒限制
• 命令行工具: 提供简单的 init 和 reverse 命令

安装

# 从源码安装
git clone <repository-url>
cd eggpy
pip install -e .

或通过 pip 安装：

pip install -i https://cnb:dUkPqqz3kZhg9G1337n9bZQZShD@pypi.cnb.cool/Astronaut-Leica/Lecca/-/packages/simpleeggpy

使用方法

初始化项目

在包含 Lua 文件的目录中运行：

python -m eggpy init

此命令会：

1. 扫描当前目录下的所有 .lua 文件
2. 将它们转换为 Python 文件（保存在 eggpy/ 目录中）
3. 根据 EggyAPI.lua 生成 Python API 定义（保存在 eggpy/api/ 目录中）

编写 Python 文件

转换后，你可以在 eggpy/ 目录中编写和修改 Python 文件。注意：

• 遵循生成的 API 定义
• 避免使用蛋仔沙盒不支持的 Python 特性
• 参考 eggpy/api/ 中的类型定义

反向转换

当你完成 Python 开发后，运行反向转换：

python -m eggpy reverse

此命令会：

1. 扫描 eggpy/ 目录下的所有 .py 文件
2. 将它们转换回 Lua 文件（覆盖原文件或生成到指定目录）

命令行参数

init 命令

python -m eggpy init [选项]

选项：

• --input-dir PATH: 指定输入目录（默认为当前目录）
• --output-dir PATH: 指定输出目录（默认为 eggpy/）
• --api-dir PATH: 指定 API 输出目录（默认为 eggpy/api/）
• --skip-api: 跳过 API 生成
• --verbose: 显示详细输出

reverse 命令

python -m eggpy reverse [选项]

选项：

• --input-dir PATH: 指定输入目录（默认为 eggpy/）
• --output-dir PATH: 指定输出目录（默认为当前目录）
• --overwrite: 覆盖已存在的 Lua 文件
• --verbose: 显示详细输出

原理

eggpy 的工作原理基于以下几个步骤：

1. 解析阶段: 使用 Lua 解析器读取 Lua 文件，构建抽象语法树（AST）
2. 转换阶段: 将 Lua AST 转换为等效的 Python AST
3. API 映射: 将蛋仔特有的 API（如 math.Vector3、dict()）映射到对应的 Python 实现
4. 代码生成: 从 Python AST 生成 Python 源代码
5. 反向转换: 类似地，将 Python AST 转换回 Lua AST 并生成 Lua 代码

关键转换规则：

• Lua 表（table）转换为 Python 字典（dict）或列表（list）
• Lua 函数（function）转换为 Python 函数（def）
• 蛋仔的 Fixed 类型转换为 Python 的 float（但受范围限制）
• math.Vector3 和 math.Quaternion 转换为对应的类

API 文档

数据类型

蛋仔游戏支持以下特殊数据类型：

• Fixed: 定点数，范围 -2147483647.0 ~ 2147483647.0
• integer: 整数，向下取整
• Vector3: 三维向量，包含 x, y, z 分量
• Quaternion: 四元数，用于旋转表示
• dict: 支持任意类型键的字典（使用 dict() 创建）

数学库

蛋仔的 math 库与标准 Lua 不同：

# Python 中的使用示例
import math

# 转换函数
value = math.tointeger(3.14)  # 转换为整数（向下取整）
fixed = math.toFixed(100)     # 转换为定点数

# 三角函数（输入为弧度）
sin_val = math.sin(math.pi / 2)
cos_val = math.cos(math.pi)

# 反三角函数（返回弧度）
angle = math.asin(0.5)

# 取整函数
rounded = math.round(3.5)
ceiled = math.ceil(3.1)
floored = math.floor(3.9)

# 值限制
clamped = math.clamp(value, 0, 100)

向量与四元数

# 创建向量
from eggpy.api.vector import Vector3

vec = Vector3(1.0, 2.0, 3.0)
print(vec.x, vec.y, vec.z)  # 1.0 2.0 3.0

# 向量运算
length = vec.length()
unit_length = vec.normalize()
dot_product = vec.dot(Vector3(4.0, 5.0, 6.0))
cross_product = vec.cross(Vector3(4.0, 5.0, 6.0))

# 四元数
from eggpy.api.quaternion import Quaternion

rot = Quaternion(pitch=0.0, yaw=90.0, roll=0.0)
inverse_rot = rot.inverse()
rotated_vec = rot.apply(vec)

字典类型

# 创建支持任意类型键的字典
from eggpy.api.dict import dict

my_dict = dict()
key = Vector3(1, 2, 3)
my_dict.set(key, "value")
value = my_dict.get(key)

# 遍历字典
for key, value in my_dict.keyvalues():
    print(f"Key: {key}, Value: {value}")

for key in my_dict.keys():
    print(f"Key: {key}")

for value in my_dict.values():
    print(f"Value: {value}")

环境限制

蛋仔游戏运行在安全沙盒中，有以下限制（详见 doc/1.txt）：

移除的库：

• io, os, package, debug

重新实现的库：

• math（支持定点数和整数）

语法限制：

• 不支持字符串和数字间的隐式转换
• 表的键只能是数字或字符串（除非使用 dict()）
• 使用 dict() 创建支持其他类型键的字典

开发者模式（仅限 PC 编辑器）：

• 内置 LuaSocket 库
• 解除表键类型限制
• 允许使用 io 和 debug 库

重要提示：开发者模式只在 PC 编辑器内试玩时有效，发布的游戏不能依赖这些功能。

开发指南

项目结构

project/
├── doc/
│   ├── README.md           # 本文档
│   ├── EggyAPI.lua         # 原始 API 定义
│   └── 1.txt              # 环境限制文档
├── eggpy/                 # 转换后的 Python 文件
│   ├── api/               # 生成的 API 定义
│   │   ├── __init__.py
│   │   ├── math.py
│   │   ├── vector.py
│   │   ├── quaternion.py
│   │   └── dict.py
│   └── main.py            # 示例转换后的文件
├── setup.py              # Python 包配置
└── requirements.txt      # 依赖项

模块拆分

原始 EggyAPI.lua 文件已拆分为以下模块：

1. math: 数学函数和常量
2. vector: Vector3 类型及相关操作
3. quaternion: Quaternion 类型及相关操作
4. dict: 字典类型及相关操作
5. core: 核心全局函数和变量

第三方库隔离

为确保生成的代码能在蛋仔沙盒中运行，eggpy 遵循以下原则：

1. 不引入外部依赖: 转换后的代码不依赖任何 Python 第三方库
2. API 模拟: 在 Python 中模拟蛋仔 API 的行为
3. 类型检查: 提供类型提示但不强制依赖 typing 模块
4. 兼容性验证: 转换后验证代码是否符合沙盒限制

贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 开启 Pull Request

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。