# ldlua

**Repository Path**: LYNKCOL/ldlua

## Basic Information

- **Project Name**: ldlua
- **Description**: 基于 GGELUA2 二开优化的 2D 游戏引擎，Lua 5.4.8 + SDL2，跨平台
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-05-05
- **Last Updated**: 2026-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ldlua

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

一个免费的 2D 游戏引擎，使用 **Lua 5.4.8** 编写游戏逻辑。

**ldlua 是基于 baidwwy 的 GGELUA2 进行二开优化的版本**——保留 GGELUA2 的核心架构（class 系统、GGE/SDL/GUI/GOL 模块、跨平台模板），在其之上做了大量重写、修复与扩展，使其更适合实际项目落地。中文变量名、面向对象、跨平台支持等原始特性均完整保留。

```
平台   Windows · macOS · iOS · Android
语言   Lua 5.4.8（支持中文标识符）
渲染   SDL2 (direct3d11 / opengles2)
图形   2D 精灵、动画、文本、镜头（亚像素相机）
界面   GUI 控件库（按钮、列表、输入框、下拉、容器、主题）
网络   HPSocket（TCP Pack / Pull / RPC）
工具   ImGui、A* 寻路、SQLite、JSON、SDL-Mixer-X
```

## 特点

- **中文变量名** — 类名、方法名、变量名均可使用中文
- **面向对象** — 内建轻量 class 系统，支持继承、热更新
- **一份代码多端跑** — Windows / Android / iOS / macOS 模板 APK 一键打包
- **lua.exe 三模式** — 同一个 `lua.exe` 既是游戏入口（带 SDL 窗口），也是构建器（`-GB`/`-GR`），还能作为标准 Lua 解释器（`-v`/`-e`/`-i`/`script.lua`）

## 相对 GGELUA2 的二开优化

引擎层：

- **升级 Lua 5.4.3 → 5.4.8**，并重新编译三端（Windows/Android/iOS）
- **lua.exe 三模式路由**：游戏入口 / 构建器 / 标准解释器自动识别（兼容 VSCode F5 调试）
- **合并 gsdl2f.dll 进 ldlua.dll**，新增 `RenderCopyF`/`RenderCopyExF` 亚像素相机（`gsdl2.dll` 仍独立保留）
- **SDL2 自定义 3 处优化**：DXGI AllowTearing 突破 DWM VSync、FLIP_DISCARD 减少显存、Batching 修复
- **ghpsocket HTTPS 支持**：`HP_HttpClient` 新增 `OnHandShake` 回调，热更新并行工人改为握手后再发 GET
- **ghpsocket IPv6 支持**：TCP/Pack/Pull/Http/Udp 全系列组件适配 IPv6，地址解析与连接走 dual-stack（IPv4/IPv6 自适应）

GUI 层：

- **新增 GUI 主题模块**（`GUI/主题.lua`，中央样式管理、查询链回退、精灵工厂）
- **重写下拉列表控件**（455 行替代旧 930 行 AI 版 + 120 行组合.lua，含可编辑搜索 + 完整样式 API）
- **修复 IME 输入法 bug**：PC 退格删除已提交内容、Android TEXTINPUT 后标志未清

寻路与算法：

- **修复 gastar:GetPath() 起终点同格死循环爆内存**（父指针未初始化）
- **新增最大步数安全上限 + 200k 节点展开上限**，防止寻路卡死
- **8 方向 A\* 斜向切角检查**（与梦幻西游官方寻路一致）

桌面工具：

- **新增数据库浏览器**（Navicat 风格 SQLite 管理：多连接、表浏览、SQL 查询、数据编辑、导出）
- **新增地图查看器**（直接调用 gxyq.map 加载 .map 地图）
- **新增协议参考面板**（查看 Protobuf 协议号、消息名称、字段定义）
- **新增日志查看器**（实时监控客户端/服务端日志文件）

详细变更见末尾的 [变更日志](#变更日志)。

## 限制

- 没有工具链（编辑器/关卡器）
- 没有物理引擎、粒子引擎、着色器

## 已知问题

- 输入法（IMGUI）

---

## 快速开始

### 运行项目

```bash
# 命令行（需设置 ldlua 环境变量指向引擎目录）
%ldlua%/lua.exe -GR RUN Windows <项目路径>

# VSCode：Ctrl+Shift+B 选择 "ggerun"
```

### 构建发布包

```bash
%ldlua%/lua.exe -GB BUILD Windows <项目路径>
%ldlua%/lua.exe -GB BUILD Android <项目路径>
```

### 标准 Lua 解释器模式

```bash
lua.exe -v                  # 显示版本
lua.exe script.lua          # 执行脚本
lua.exe -e "print(1+2)"     # 执行代码
lua.exe -i                  # 交互式 REPL
```

`lua.exe` 通过检测 `argv[1]` 自动路由：

| argv[1] | 模式 | SDL 窗口 |
|---------|------|----------|
| 无 / 是目录 | 游戏入口 | ✅ |
| `-GB` / `-GR` | 构建/运行 | ❌ |
| 其他（`-v`/脚本路径等） | 标准解释器 | ❌ |

### 调试

VSCode + `lua-local` 扩展，启动配置选择 **"Debug ldlua Windows"**。

---

## 项目结构

引擎自身：

```
engine/
  GGE/   # 核心引擎（class、精灵、动画、文本、坐标、镜头）
  SDL/   # SDL2 封装（窗口、图像、纹理、音频、网络、读写）
  GUI/   # 界面控件（按钮、列表、输入框、容器、下拉列表、主题）
  GOL/   # 网络层（RPC 客户端/服务端/代理）
  LIB/   # 工具库
  LUA/   # Lua 标准库扩展
```

游戏项目结构：

```
项目目录/
  lua/
    main.lua    # 入口
    ...         # 业务模块
  assets/       # 图片、声音、字体等资源
  .vscode/
    ggerun.lua  # 可选：自定义运行脚本
```

### 关键文件

| 文件 | 用途 |
|------|------|
| `ldlua.lua` | 引擎启动器、模块加载、平台检测 |
| `engine/GGE/class.lua` | 面向对象类系统 |
| `engine/GGE/GGE.lua` | 核心引擎函数 |
| `engine/GGE/镜头.lua` | 相机控制、亚像素渲染 |
| `engine/SDL/SDL.lua` | SDL2 接口 |
| `engine/GUI/GUI.lua` | GUI 系统入口 |
| `engine/GUI/下拉列表.lua` | 下拉列表控件（含可编辑搜索） |
| `engine/GUI/主题.lua` | 中央样式管理（查询链回退、精灵工厂） |

### 原生库（lib/）

| DLL | 用途 |
|-----|------|
| `ghpsocket.dll` | HPSocket 网络库 |
| `gastar.dll` | A* 寻路算法（支持 string 数据初始化） |
| `gimgui.dll` | ImGui 集成 |
| `lsqlite3.dll` | SQLite 数据库 |
| `cjson.dll` | JSON 解析 |
| `gsdl2.dll` | SDL2 Lua 绑定（窗口/精灵/纹理/音效/事件） |
| ~~`gsdl2f.dll`~~ | 已合并至 `ldlua.dll`（含 `RenderCopyF`/`RenderCopyExF` 亚像素相机） |

---

## 渲染器与帧率

| 平台 | 渲染器 | 备注 |
|------|--------|------|
| Windows | `direct3d11` | 默认，配合 AllowTearing 突破 DWM VSync |
| Android / iOS | `opengles2` | — |

### SDL2 自定义修改（仅 Windows）

SDL2 源码静态链接到 `ldlua.dll`，包含 3 处自定义优化：

| 优化 | 说明 |
|------|------|
| DXGI AllowTearing | 窗口模式突破 DWM 60fps VSync 锁定（Win10 1803+） |
| FLIP_DISCARD | 替代 FLIP_SEQUENTIAL，减少显存开销 |
| Batching 修复 | 指定渲染器名称时保持 draw call 批处理 |

Android 端使用模板 APK 内置的 `libSDL2.so`，不受影响。

### 渲染器标志

`SDL/窗口.lua` 中 `CreateRenderer` 的 flags：

```
SDL_RENDERER_ACCELERATED   = 0x02
SDL_RENDERER_PRESENTVSYNC  = 0x04
SDL_RENDERER_TARGETTEXTURE = 0x08

无 VSync: rflag = 10  (ACCELERATED | TARGETTEXTURE)
有 VSync: rflag = 14  (ACCELERATED | PRESENTVSYNC | TARGETTEXTURE)
```

---

## 网络模式

引擎支持三种网络模式：

| 模式 | 说明 |
|------|------|
| **PACK** | TCP Pack 模式（HPSocket） |
| **PULL** | 拉取式消息 |
| **RPC** | 远程过程调用（客户端 / 服务端 / 代理） |

---

## 致谢

- **baidwwy** — GGELUA2 原作者，本项目核心架构（class、GGE/SDL/GUI/GOL）来自其多年积累
- **GGELUA2 历代贡献者** — 见关于窗口的"特别感谢"

## 交流群

QQ 群：**游戏开发交流群**（群号 `19453462`）

[点此加入](https://qm.qq.com/q/bA5eGQX98A) 或扫描下方二维码：

<img src="./docs/images/qq-qrcode.jpg" alt="QQ 群二维码" width="240">

---

## License

[MIT License](./LICENSE) — 自由使用、修改、分发、商用，仅需保留原作者声明。

ldlua 衍生自 baidwwy 的 GGELUA2，上游代码版权归原作者所有；本项目的修改与扩展按 MIT 协议开放。

## 开发约定

详见 [CLAUDE.md](./CLAUDE.md)（代码规范、性能陷阱）。

---

## 变更日志

> **说明**：本变更日志包含两个阶段：
> - **2026.02.26 起** — ldlua 二开期（在 GGELUA2 之上的优化、修复与扩展）
> - **2024.06.01 及更早** — GGELUA2 上游历史变更（baidwwy 时期），保留作引擎血统记录
>
> 引擎二开自 2026.02.26 升级 Lua 5.4.3 → 5.4.8 起。

### ldlua 二开期

#### 2026.03.11

- 修复 gastar:GetPath() 起终点在同一格子时死循环爆内存（父指针 memset={0,0} 未初始化，跟随链永不终止，每步分配 lua_newtable 直至内存耗尽崩溃）
- 修复 gastar:GetPath() 新增最大步数安全上限（= 网格总格数），彻底防止任何父指针异常导致的无限循环
- 优化 gastar:FindPath() 新增 200k 节点展开上限，防止不可达目标导致引擎长时间卡死
- 优化 gastar:FindPath() 8方向A*斜向移动增加切角检查（相邻两轴均可通行才允许走斜线，与梦幻西游官方寻路一致）

#### 2026.03.05

- 修复 PC输入法退格删除已提交内容（IME组合结束时KEYDOWN BACKSPACE未屏蔽）
- 修复 Android输入法退格无效（_输入中标志未在TEXTINPUT后清除+移动端组合中屏蔽退格）
- 修复 ghpsocket HTTPS 支持：HP_HttpClient 新增 OnHandShake 回调，SSL握手完成后才发送HTTP请求（原 OnConnect 在握手前触发，导致HTTPS发包失败）
- 修复 ghpsocket-build ndk-build：Android.mk 新增 HP_HttpClient.cpp OnHandShake 实现，重新编译 libghpsocket.so
- 修复 热更新 Pack/并行工人 HTTPS 支持：连接事件改为等握手事件后再发 GET（原工人无握手事件，HTTP 请求在 SSL 握手前发出导致服务器断开，Pack 下载 0 字节中断）
- 添加 ghpsocket IPv6 支持：TCP/Pack/Pull/Http/Udp 全系列组件适配 IPv6，地址解析与连接走 dual-stack（IPv4/IPv6 自适应）

#### 2026.02.27

- 添加 GUI主题模块（GUI/主题.lua，中央样式管理，查询链回退，精灵工厂支持）
- 修复 SDL文字:置大小() type()括号位置错误（任何类型参数都被接受）
- 修复 SDL精灵:减中心() 减法方向反转 + y误写为x
- 添加 GUI下拉列表控件（重写，455行，替代旧930行AI版+120行组合.lua）
- 添加 GUI下拉列表样式API（背景/按钮精灵/弹出背景/列表颜色）
- 添加 IMGUI下拉列表示例（desktop工具菜单，5种用法演示）
- 修复 GUI列表 残留debug print（每次点击输出8行调试信息）
- 修复 GUI列表 鼠标滚轮事件中py未定义（事件参数永远为false）
- 修复 GUI控件 右键按住检测用错掩码BUTTON_LMASK（事件永远不触发）
- 修复 GGE精灵:置过滤()/置混合() 循环变量v遮蔽参数v（传入精灵自身而非参数值）
- 修复 GGE坐标:取弧度() elseif条件中y误写为_y（table参数分支条件恒真）
- 修复 GGE坐标:随机加() local x遮蔽参数x（y缺省时取到随机结果而非原始范围）
- 修复 GGE资源:取音乐() warn输出path(恒为false)而非file（无法定位缺失文件）
- 修复 IMGUI基类控件:_更新()参数用...但引用未定义dt（用户更新回调永远收到nil）

#### 2026.02.26

- 升级 Lua 5.4.3 → 5.4.8（最新稳定版，~26 个 bug 修复）
- 添加 标准 Lua 解释器模式（lua.exe -v/-e/-i/-l/script.lua，不启动 SDL 窗口）
- 添加 lua.exe 三模式路由（游戏入口 / 构建运行 / 标准解释器）
- 添加 目录参数检测（argv[1] 为目录时走游戏入口，兼容 VSCode F5 调试）
- 重编引擎 ggelua.dll + lua.exe + GGELUA.exe + libggelua.so + libmain.so

### GGELUA2 上游历史（baidwwy 时期）

#### 2024.06.01

- 优化编译
- 修复 非NTFS格式分区不能编译
- 修复 SDL-Mixer-X 泄露
- 修复 IOS无法连接网络
- 添加 socket依赖的mime
- 完善 SDL图形
- 升级 很多库
- 优化 精灵
- 优化 纹理
- 优化 资源
- 优化 文字直显

#### 2023.11.01

- 修复 4:3 屏幕比例
- 修复win7 输入
- cjson 整数
- 替换声音库为SDL-Mixer-X
- 提升安卓的速度 10%
- 升级 SDL
- 升级 sqlite
- 升级 HPSocket
- 升级 imgui
- 其它优化

#### 2023.08.01

- windows支持优先加载 ggelua.com
- 脚本包名改为 ggelua.com
- 升级 SDL
- 升级 sqlite
- 升级 HPSocket
- 升级 imgui
- 添加 安卓调试推送文件进度
- 修复 GGE动画 复制方法
- 修复 SDL精灵 复制时 没有复制区域
- 修复 GUI文本#b没有使用dt更新
- 添加 渲染区重建
- 添加 windows单文件编译
- 添加 socket依赖的lua

#### 2023.06.01

- 完善 GUI手机滚动
- 修复 输入法问题
- 添加 GUI输入支持表情
- 优化 GUI编辑
- 优化 GUI输入
- 优化 GUI删除控件直接索引，改成 路径索引
- 优化 镜头
- 删除 GGE矩形
- 完善 SDL矩形
- 完善 class支持父 __newindex
- 修复 class指定__index时，应先子类再父类+
- 增加 GUI摇杆
- 优化 使用rcedit写exe信息
- 优化 memcpy支持偏移
- 添加 SDL图形
- 优化 GGE函数
- 优化 循环和帧率
- 升级 lua 5.4.6
- 升级 SDL 2.26.5
- 升级 imgui 1.89.5
- 修复 astar泄漏
- 修复 wav破音
- 合并windows的dll到ggelua.dll
- 修复 package.path在安卓无效
- 添加 安卓远程调试
- 优化 安卓调试
- 添加 SDL网络
- 添加 ggeprint 能显示代码位置
- 优化 安卓包名不能以数字开头
- 增强 GUI控件 支持非裁剪
- 优化 重写GUI列表，树
- 增加 GUI容器
- 修复 KEY_ESCAPE 错误
- 增强 GGE文本 添加#m居中
- 修复 判断目录
- 增加 SDL图像:九宫
- 修改 SDL图像:到精灵() 支持置区域
- 修改 GGE坐标的pack,unpack改为set,get
- 修复 线程 nil参数
- 大量优化

#### 2023.03.01

- 修复 图像:检查透明 错误
- 修复 24位图像检查透明为true
- 修复 纹理:到精灵 在多窗口错误
- 修复 多窗口取坐标错误
- 修复 SDL读写异常释放
- 修复 坐标移动精度问题
- 增加 GGE精灵
- 增加 GGE镜头
- 重写 线程
- 修改 HPSocket消息回调方式
- 修复 RPC地址重复问题
- 删除 serialize
- 其它优化
- 升级 SDL2 2.26.3
- 升级 SDL2 ttf 2.20.2
- 升级 imgui 1.89.3

#### 2023.01.20

- 完善 GUI
- 删除 gip
- 添加 ip2region
- 安卓 添加luasql sqlite3
- 升级 imgui 1.89.2
- 升级 HP-Socket 5.9.1
- 升级 Sqlite 3.40.1
- 升级 SDL2 2.26.2
- 升级 SDL_image 2.7.0

#### 2022.12.25

- 修复 APK图标
- 修复 APK包名不能为game
- 修复 修复有错误时，无限弹框
- 修复 SDL矩形显示时，不使用中心
- 修复 安卓逻辑宽高偶尔无效
- 优化 线程
- 优化 serpent支持中文key
- 优化 GOL 默认主线程收数据
- 优化 csv可以call(str)
- 例子 传奇技能
- 例子 线程
- 例子 坐标
- 例子 ZIP
- 例子 serialize
- 修复 IMGUI 左键弹起
- 增加 GGE资源 添加ZIP支持
- 升级 SDL2 2.26.1
- 升级 SDL2 image 2.6.2
- 升级 SDL2 mixer 2.6.2
- 升级 imgui 1.89.1
- 升级 apktool 2.7.0

#### 2022.11.11

- 修复 宋体英文数字模糊问题
- 修复 IMGUI宋体模糊问题
- 修复 IMGUI 纹理按钮
- 修复 文字复制，不对应窗口
- 修复 RPCAGENT
- 修复 控制台错误时，没有信息
- 修复 文件独占时，是否存在 无法检查到
- 修复 渲染器无法设置
- 修复 编译后，目录错误
- 修复 编译后，loadfile环境表错误
- 优化 编译后，弹出编译目录
- 修复 安卓不能竖屏
- 修复 安卓 xml 和 openssl
- 优化 渐变播放 合并到 播放
- 增加 线程
- 增加 EXE写图标和版本
- 增加 自动更新
- 增加 创建项目
- 增加 浏览项目
- 增加 ST编辑器
- 增加 HP代理客户端例子
- 增加 WIN进程通信例子

#### 2022.9.10

- 分割文本 不再使用正则
- ggexpcall 现在错误时返回 gge.FALSE
- GGE日志 改用log
- 定时添加 删除
- 定时现在是弱引用的
- 修复 定时器 invalid key to 'next'
- 修复 GOL崩溃没错误显示
- RPC添加了超时 1分钟无返回则清除
- 修复RPC无返回时崩溃没错误
- GUI大量修改，仍然不是正式版
- SQLITE 添加了修改和增加方法 update test set data=? - where id=1
- SQLITE BLOB现在可以正确的获得?号参数
- windows现在默认opengl渲染器
- 修复截图时宽高过小，导致崩溃
- 修复精灵 置区域 nan
- 修复精灵拉伸后检查点错误
- 修复音效
- 增加文字对齐
- 窗口置坐标时，留空则居中
- 添加多点触摸事件
- 修复寻路崩溃
- 修复一处内存泄露
- 添加xml
- 添加openssl
- 添加一些例子

#### 2022.5.13

- 优化 VSCode默认从cmd
- 修复 内存释放
- 修复 SDL窗口FPS
- 修复 SDL动画从读写载入
- 升级 SQLite3.38.5
- 优化 SDL图像:取像素 支持8位图
- 优化 SDL图像:取像素 返回RGBA
- 优化 SDL图像:取关键色 返回RGBA
- 优化 TGA载入 以同步官方SDL_image
- 修复 gge.arg在调试时无法收到参数

#### 2022.4.29

- 优化 class 支持重写(热更新)
- 优化 class 支持pairs
- 添加 GGF遍历文件(不遍历子目录)
- 改名 GNET->GOL
- 添加 GOL类(用于服务端)
- 修复 astar崩溃
- 优化 窗口启动默认黑屏
- 优化 FPS显示
- 修复 多窗口FPS
- 添加 异形窗口
- 修复 精灵:置过滤()
- 修复 空白精灵:取透明()
- 修复 图像载入
- 添加 图像:到纹理()
- 添加 图像:置透明色()
- 优化 重复文字内存(使用同个字体，不同大小或样式的)
- 修复 音效重复播放
- 升级 SDL 2.0.22
- 升级 HP-Socket 5.8.8
- 添加文档
- 添加例子
- 其它优化

#### 2022.3.25

- 修复 package.loaded索引
- 修复 SDL窗口 未创建时，导致死循环
- 修复 SDL窗口 置逻辑宽高 0无法取消
- 修复 SDL图像 渲染开始 无法设置底色
- 优化 GGE资源 现在可以自定义加载源
- 优化 class 当初始化return false 时，不再返回对象
- 优化 GGF.复制文件 现在会创建目标目录
- 优化 GUI
- 添加 GGE文本 置文字表
- 添加 GGE文本 置精灵表
- 添加 GGE动画 置坐标
- 添加 SDL精灵 置坐标
- 添加 一些基础例子
- 升级 HP-Socket 5.8.7
- 删除 SDL精灵 显示中心
- 删除 SDL精灵 显示矩形

#### 2022.3.6

- 添加 旧地图支持
- 添加 RWread 到MEM
- 完善 SDL_Memory
- 完善 imgui
- 升级 imgui 1.87
- 其它优化

#### 2022.2.20

- 修复 TGA无法从内存载入
- 修复 windows 运行时编译
- 优化 注册事件
- 完善 IMGUI
- 添加 拖放文件事件WINDOWEVENT_DROPFILE

#### 2022.2.13

- 增加 doc
- 增加 QOI图像支持
- 修复 SDL.写出文件 未关闭
- 修复 lua文件路径过长导致显示不全
- 修复 部分lua错误不显示回溯
- 修复 lfs文件路径超过260崩溃
- 其它优化
- 修复部分机型分辨率导致的错误
- 完善安卓调试
- GUI按钮碰撞使用检查点

#### 2022.2.6

- 增加  gsm wav 支持
- 优化 安卓 字体载入到内存
- 修复 安卓 直接使用require时不能找到资源
- 修复 GUI鼠标事件
- 增加 引擎:创建窗口（创建一个子窗口）

#### 2022.1.30

- 升级 lua 5.4.4
- 添加 nanoid和uuid
- 修复 vscode插件推荐提示
- 添加 zeromq