台服DNF服务器插件《Df Plugin开发文档》（内置lua脚本系统仅支持dfgame进程）

爱吃土豆丶 · 发表于 2023-4-8 22:33:28

本帖最后由爱吃土豆丶于 2023-4-9 11:56 编辑

《Df Plugin开发文档》

作者：sidyhe

概述

dp 全称为 df plugin
它是一款服务器插件, 使用补丁技术扩展其功能
并内置 lua 脚本系统使得各功能自由定制, 以满足各种需求
目前仅支持 dfgame 进程, 其他进程暂无需求
本插件不适合小白用户, 如果你不了解 linux 常用命令和 lua 编程, 建议放弃
PS: 由于 2.6 版本对 fac 做了一些不兼容的修改, 所以 2.5 的代码无法直接使用

使用前提
请确保服务器可以正常运行, 再安装插件!!!
问题反馈
anywaies@hotmail.com
安装步骤
把提供的 dp2 目录复制到服务器根目录下
目录位置及名称不可修改, 否则无法正常工作

核心文件

/dp2/libdp2pre.so	加载器 1
/dp2/libGeoIP.so.1	加载器 2
/dp2/libdp2.so	插件框架
/dp2/libdp2.xml	插件框架配置
/dp2/lib/	额外模块目录
/dp2/lua/	脚本库目录 (第一优先级)
/dp2/lua2/	用户脚本库目录 (第二优先级)

一般来说用户不需要修改 lua 目录下的文件, 版本更新时删掉原有的 lua 目录, 再覆盖新的!
而 lua2 目录属于用户代码, 自行编写的功能放在这里, 安装包内默认为空主要文件

适用于 df_game_r 的插件扩展模块

/dp2/lib/libdp2game.so

复制代码

安装方法
本插件提供两种加载方式(两种加载器), 选择其中 1 种即可
PS: 不要看到什么模块用了 LD_PRELOAD 就蒙圈, 第二种加载方式也可以!

加载器 1
本节使用 LD_PRELOAD 方式加载插件

selinux

复制代码

首先, 关闭 selinux 功能, 若已关闭, 忽略
在 root 权限下输入

setenforce 0

复制代码

注意这种方法是临时关闭, 系统重启后会恢复
若需永久关闭, 请自行查阅资料

调整启动命令
在启动 dfgame 命令行(常见一键端是 run 文件)中, 添加 LD_PRELOAD 启动参数
如

./df_game_r cain01 start &

复制代码

变成

LD_PRELOAD=/dp2/libdp2pre.so ./df_game_r cain01 start &

复制代码

即在最前面新增

LD_PRELOAD=/dp2/libdp2pre.so

复制代码

注意每一块参数之间的空格

加载器 2
本节使用替换依赖库的方式加载插件
这种方式只适用于 dfgame 进程, 若需其他进程支持插件, 参阅上一节替换文件
在 root 权限下依次执行如下命令

cd /usr/lib
rm -f libGeoIP.so.1
ln -s /dp2/libGeoIP.so.1

复制代码

或者

cd /usr/local/lib
rm -f libGeoIP.so.1
ln -s /dp2/libGeoIP.so.1

复制代码

搞定

启动流程
选择 1 种加载器安装插件之后, 会统一加载核心模块 libdp2.so，而核心模块会去/dp2/libdp2.xml 读取配置
根据当前进程的文件名, 加载配置中对应的插件扩展

确定当前进程名称, 找到 xml 节点
读取 deps 节点, 并按顺序加载 so 模块 (用于解决后续 so 的符号依赖)
读取 script 节点内容, 并暂存
读取 plugin 节点, 加载并启动这个模块

以 dfgame 为例
df_game_r 启动, 加载器加载 libdp2.so
libdp2.so 初始化并加载配置文件 /dp2/libdp2.xml
libdp2.so 查找配置文件中 "df_game_r" 的项, 加载依赖, 加载扩展 (libdp2game.so)
libdp2game.so 初始化并向核心模块索要 lua 主文件路径 (配置)
libdp2game.so 执行 lua 文件注意事项
直到扩展模块初始化之前, 是没有日志系统的
也就是说如果产生异常或错误, 消息日志会输出在控制台上
建立日志系统之后, 消息会输出至文件中, 文件存放于进程位置的 log 目录下
在 dfgame 扩展中, 位于 log/cain01/dp-${date}.log, 日志文件每天滚动
其中 cain01 是启动 dfgame 时的第二个参数
查看日志是一个好习惯, 能够很好的解决问题
PS: 常见一键端 dfgame 的 dp 日志位于 /home/dxf/game/log/ 中

开发文档
由于失误, 删除了 2.5 的文档源文件
又因为更新文档繁琐, 故采用代码文档的方式, 需要安装 idea 和 immylua 插件
插件开放的接口仅存在于_DP 和_DPX 全局模块内

_DP
通用功能, 与游戏逻辑无关的方法

_DPX
特定功能, 与具体进程有关的方法

文档怎么看
首先安装开发环境, 参见开发文档.pdf
本插件的所有 sdk 内容位于 lua/df 中
插件的_DP 和_DPX 接口位于 lua/df/doc 中
其他扩展接口都以 lua 源码的形式实现, 参见 lua/df/ 内的所有文件
另外, 插件也附带了很多通用 lua 模块, 参见 lua/readme.md
如果你有能力自行编译 lua 模块, 压缩包内也提供 lua 的头文件, 链接 liblua53.so 即可关键点 (非常重要)

在 lua 中会以某些方式获得游戏对象指针(lightuserdata), 叫做原始指针: cptr
原始指针可以被 ffi 库使用 (luaffi 和 lua-alien)
luaffi 使用的指针需要经过一次 cast 转换, 叫做: fptr. 但 alien 可以直接使用 cptr
内置的 fac 库可以把 cptr 包装成 lua 对象, lua 对象内部持有 cptr 和 fptr
如 user 的 fac 库, 就是把 cptr 进行包装, 看起来像是 lua 对象, 其本质是通过 ffi 调用游戏内自有的 C/C++函数, 结合 lua 逻辑, 共同实现功能扩展.
插件自身除了使用 C++实现了部分关键功能, 其他绝大部分逻辑都由 lua+ffi 实现

注意: 在 lua 中小心使用任何 cptr 和 fptr!

常见问题

Q: 对服务端有要求吗?
A: 无, 能正常启动并跑五国即可

Q: 为什么按照步骤安装插件却毫无效果?
A: 先看有没有 dp 日志, 若没有, 则启动环境配置有误, 否则查看日志确定问题

Q: 如何修改 dp 默认位置?
A: 有三件事情, 如下:

设置环境变量 DP2SO 修改 libdp2.so 路径
设置环境变量 DP2XML 修改 libdp2.xml 路径
主 lua 脚本第一件事是修改 lua 的 search path 变量 (或自行编译 liblua53.so, 更麻烦)

Q: 出现 ERROR: ld.so: object '/dp2/libdp2pre.so' from LD_PRELOAD cannot be preloaded:ignored., 如何解决?
A: 这是由于使用 lua 调用外部程序导致的. 原理是使用了 LD_PRELOAD 加载 dp, 而 dp 和游戏服务器是 32 位进程, 系统为 64 位, 且 LD_PRELOAD 有继承机制(即 64 位进程想加载 32 位模块被拒绝). 解决方法: 使用加载器 2, 或者忽略它, 不影响.

更新历史
v2.8.0 – 20230330