rpze 0.2.3

rpze: Remote Python, Zombie: Endless

rpze

Remote Python, Zombie Endless (or endless rp?)

一个远程 Python 的 Plants vs. Zombies (pvz) TAS / 修改器 及 I, Zombie Endless (ize) 测试框架.

介绍

rpze 是一个用于 ize 测试的框架, 旨在保持一定性能、高精度、少崩溃的同时大幅简化 ize 非定态测试脚本的编写.
通过与注入游戏的.dll进行 ipc 以实现理论100%精度和不崩溃的原版函数调用.

支持平台

仅支持 Windows 上的 CPython >= 3.11:

• 3.11及以上的 CPython 仅支持 Windows 10 及以上平台
• pypi 上提供了64位 cp311, cp312 的预编译.whl.
• 32位平台原则上支持, 但需要自行构建

仅支持1.0.0.1051版本 pvz , 测试以 pt 站上的英语原版 (lcx 版)为准. 原则上支持各类汉化版, 不支持 jspvz 上的英语原版. 各种其他来源的“英语原版”有不小概率出自 jspvz 或者同样没去登录壳, 请注意.

安装

在满足上述平台要求后, 执行python -m pip install rpze即可.
若想确认安装成功, 执行python -m rpze --path "your\path\to\PlantVsZombies.exe", 若游戏正常启动且在加载界面加载到一半时自动运行生物钟脚本, 则安装成功.

常见安装 FAQ

为什么弹出一个黑色窗口显示 console set?

这是正常现象, 无须多注意. 用于确认成功以及在跳帧时关闭游戏等.

游戏正常启动但并不自动运行脚本 / invalid command / failed to find shared memory?

重新阅读支持平台. 请考虑你使用的版本是否符合上述要求. 请注意, 仅确保兼容 lcx 版!!!

failed to create shared memory / 未找到文件?

请再运行一次试试, 可能和杀毒有关; 若一直这样请和我反馈.

xmake is not installed?

重新阅读支持平台. 你使用的 Python 没有预编译.whl, 你可以选择换一个 Python 或者构建.

DLL load failed while importing rp_extend?

原因未知, 请跟我反馈. 一定有效但非常麻烦的方法是自行构建, 一个不确定是否好用的解决方法是python -m pip install msvc-runtime.

怎么联系?

加 QQ 群 884871715 或通过 GitHub issue / pr.

使用

一个简单的完整 rpze 脚本示例如下:

from rpze.iztest import *

with InjectedGame(r"your\path\to\pvz.exe") as game:
    iz_test = IzTest(game.controller).init_by_str('''
                 1000 -1
                 3-0 4-0 5-0 3-3
                 .....
                 .....
                 bs3_c
                 b2ljh
                 blyl_
                 cg   cg   xg   ww
                 0    1    300  700
                 4-6  4-6  4-6  4-6''')
    print(iz_test.start_test(True))

结构

总体分成五个包:

• rp_extend: 对控制 pvz 游戏本地运作的基本操作的封装
• basic: .dll注入, 游戏启动, 汇编代码等基础功能
• structs: pvz 内数据结构以及部分 method 的的封装
• flow: coroutine-like 测试编写相关的函数
• iztest: IzTest测试功能以及工具函数
• examples: iztest编写例子

其中, 若仅对 Python pvz 框架感兴趣则只需关注前三个包, 对 ize 测试感兴趣则着重模仿examples并大致了解structs的成员(Plants和Zombies).

优缺点

优点:

• 使用普及度最高的 Python 编写, 尽可能做到低上手难度
• 稳定性大幅领先几乎所有远程工具, 并且实现100%精度
• 作为普通 Python 包发布, 无须编译 C++ 繁琐的配置环境
• 相比于 AvZ 等方案更能和原有语言生态整合, 可以简单直接引用外部库, 处理测得数据等
• 兼容过去的 iztools 工具以及各类简写, 对已有习惯友好

缺点:

• 跳帧性能不如 AvZ, iztools 等注入框架
• 相比于向.exe静态添加汇编和.dll注入等方案, 不够原生而存在大量性能浪费.
• 支持平台过少 (>=win10, >=cpy311) 使得大量 win7 玩家无法使用
• 对 ize 以外模式的键控暂无支持, 操控游戏底层实现(如跳帧)可能因为和Board耦合过高而不够通用.
• 作者太菜了, 对软件工程和操作系统变成没有基本认知, 会存在大量浪费时间的试错和重构

鸣谢

Reisen - 提供初始思路, 模型以及解答各种问题,
63enjoy, Ghastasaucey(BiliBili) 等 - 反汇编结论参考以及教学,
vector-wlc/AsmVsZombies - 重要功能汇编函数参考,
sqrt07/iztools - 测试字符串, 功能和简写标准参照,

以及指针表, 函数表等资源工具和各位玩家的鼎力支持.

使用的开源项目

• pybind/pybind11, LICENSE
• TsudaKageyu/minhook, LICENSE
• keystone-engine/keystone, FOSS License Exception

构建

100% certified works on my two machines

本框架采用 xmake 构建, 管理二进制依赖; 使用 MSVC 编译.

安装二者后, 构建 Python .whl只需python -m pip install build后python -m build即可.

可以用python hatch_build.py -other_xmake_args来自动设置 xmake config 的编译 arch

贡献

请向 dev分支提交pull request, 请遵循 PEP 8 和项目原有的命名, 文档规范.

作者个人强行规定的规范包括但不限于:

• import本项目内文件请使用相对导入
• 标准库import与本项目import间空一行
• 请勿使用中文标点
• 单下划线即标识 protected , 不确保兼容性
• 所有 public 函数均需有 type hint 与 docstring
• 0 warning, 受不了的可以加# type: ignore或# noqa等

作者水平很菜但热爱吹毛求疵, 请不要感到气馁, 他真的很欢迎每一个帮助本项目越来越好的人.

许可

Copyright © 2024 ObeliskGate

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.