xavierchn / x-template

DOTA2自定义游戏开发模板项目，使用typesscript和react开发; Xavier's DOTA 2 custom game template using typescript and react-panorama

Russian lang

中文说明

English Readme

简单的视频教程（中文） a starter video tutorial (Chinese)

视频录制的比较早，目前已经转换为yarn作为npm包管理工具，请自行将视频中的npm改为yarn

X-Template

Xavier 的 dota2 自定义游戏开发模板

使用步骤

新建项目

1. 点击使用本项目作为模板生成你自己的项目或者 fork 本项目
2. 安装node.js，目前的要求是>16.0.0
3. clone 你使用模板生成的或者 fork 的项目
4. 安装好vscode之后和下方DOTA2 Modding 工具推荐 相关软件后，使用vscode打开clone的文件夹
5. 打开scripts/addon.config.js，将addon_name修改为你的项目名称
6. 执行yarn install安装依赖，他应该会自动 linkcontent,game文件夹到你的dota 2 beta/dota_addons (如果碰到权限问题，请关闭代码编辑器后使用控制台来执行yarn，或者重启一下电脑再试，如果碰到安装错误，可以尝试使用npmmirror镜像，或者直接执行yarn config set registry https://registry.npmmirror.com再执行yarn install)
7. yarn dev，开始你的开发
8. 如果你要启动你的项目，你可以使用指令yarn launch map_name启动游戏并载入地图，或者使用yarn launch只是启动工具而不载入地图，之后再在控制台使用指令载入地图。

从已有的项目迁移

流程同新建项目，只不过在5后插入一个

6. 将原有项目的content和game文件夹覆盖到本项目中的 content 和 game 文件夹

• 当然，你需要处理好原有的内容的 .gitignore，因为本项目默认不追踪 content/panorama/layout/ 目录 和 game/scripts/vscripts/ 目录的变更
  • 如果后端要混合使用lua和ts，请将lua代码复制到src文件夹，为了可以有代码提示，你需要自己写一个 *.d.ts 文件来提供类型声明，如果要使用 import 语句，请对lua脚本进行适当的修改，可以参考对 game/scripts/src/utils/timers.lua的改造及他对应的 d.ts 文件
  • 如果前端要混合使用xml和react，请对应修改 webpack.dev.js，主要是要删去 PanoramaManifestPlugin 部分，来自己编辑 custom_ui_manifest.xml，更推荐的做法是将 传统 panorama 写法的代码放到 src 文件夹，之后使用 webpack 共同打包

使用这个模板的好处

1. 可以使用更为现代的语言来进行开发，也就是typescript，而不是用lua和javascript，等于可以少学一门语言。
2. 使用表格工具来填写并管理你的kv文件，而无需掌握他们的结构。
3. 使用react来开发UI可以更好地管理你的代码，而无需掌握xml的写法。
4. 帮助解决了V社的工具中诸如UI无法读取KV文件，UI图片不会自动编译等问题。
5. 加密发布代码的支持，可以帮助你保护一些关键代码。

支持的功能

1. 前端的content/panorama/src与后端的game/scripts/src文件夹分别用来写用户界面 react 源码和游戏逻辑的 ts 源代码
2. 将你的 excel 文件变成 kv 文件并放到game/scripts/npc文件夹，同时在panorama和scripts文件夹生成与每个kv文件对应的json文件，这样你的ts代码可以很方便地获取kv数据
3. 将 addon.csv 变成 addon_*.txt，(也可以把 addon_*.txt 变成 addon.csv)
4. 将服务器API转换为typescript接口，同时提供了一个有效的请求类用来处理请求，使用的是 openapi-typescript-codegen

支持的指令

1. yarn launch [[addon_name] map_name] 启动 dota2，两个参数为可选参数，如果提供了addon_name那么会载入指定的 addon（默认该项目），提供了map_name则会自动载入对应的地图名（若未提供 addon_name 则默认载入当前 addon）
2. yarn dev 进入 dev 模式，将会执行将后端的ts代码编译成lua代码、使用webpack打包前端代码、同步KV到js，生成localization，Excel转KV等操作，正常来说，每次开发你需要保持yarn dev的运行状态
3. yarn prod 执行发布操作，将会自动生成publish文件夹并自动 link 到dota_addons/you_addon_name_publish文件夹，之后你可以选择这个文件夹发布（可以在package.json -> dota_developer中对发布进行一些设置）。

PS. 加密发布流程

将 scripts/addon.config.js 里面的 encrypt_files 变量根据你的需要修改，哪些文件加密，哪些不加密（解密脚本，入口文件不能加密，客户端会使用到的技能和Modifier代码建议也不加密，不要尝试通过将密钥发送给客户端这样的操作来加密客户端脚本，因为别人可以通过读内存等等方法获取到密钥）

将该文件中的 encryptDedicatedServerKeyRelease 修改成你的图的 DedicatedServerKey

key的获取方法：不加密上传一次，去获取KEY,要注意，获取KEY的 version 参数应该和 decrypt.lua 中的保持一致，你也可以上传这个项目去批量获取一些key，之后根据需要使用某一个key

执行yarn prod 来完成测试加密流程（在加密范围内的代码有变更之后需要执行，一般是要确认新加的功能能否在加密后正常运行）

确认一切运行正确后，执行 yarn prod 来完成正式发布加密流程

执行yarn launch your_addon_name_publish来启动加密后的图，之后执行上传操作（注意，这个时候本地的publish是不能正常运行的，因为密钥只有服务器上有，因此直接上传即可）

• 注意：要使用加密功能，需要安装 Lua 命令行程序（如果未安装会提示未找到lua命令）

4. yarn api 生成与 scripts/server_api.json （需要符合Swagger 3.0规范）的API一致的请求类，并储存于 game/scripts/src/server/services，关于请求实现的细节，请查阅 game/scripts/src/server/core 文件夹

文件夹内容

• content 会和 dota 2 beta/content/dota_addons/your_addon_name 同步更新
• game 会和 dota 2 beta/game/dota_addons/your_addon_name 同步更新
• shared 用来写panorama ts和tstl公用的声明，如custom_net_tables等
• scripts 各种 node 脚本，用来完成各种辅助功能
• 请仔细查阅 gulpfile.ts 来查看 gulp 的使用方法

DOTA2 Modding 工具推荐

node.js, LuaForWindows , Python 等一系列环境的配置请自行使用搜索引擎完成，不赘述。

只推荐使用steam启动dota2的形式来完成modding，如果尚未安装，请点此下载

需要安装的软件包括：

1. 代码编辑器 Visual Studio Code 或者其他你习惯使用的typescript代码编辑器
2. 反编译工具 ValveResourceFormat（推荐）或者 GCFScape(已略过时，某些格式反编译不了，但是速度比较快，推荐都安装)
3. Adobe系列工具, 如PhotoShop（必须）, Audition（选装）等，请到 官网 下载或自行使用搜索引擎获取
4. 代码版本控制 Github Desktop（推荐，和github的配合比较好） 或 SourceTree 或 TortoiseSVN
5. 模型编辑器Blender Steam直接安装【steam://install/365670】 Steam商店页面 （用自己顺手的就行，如果不涉及模型编辑可略过）
6. 其他实用工具： 文件搜索工具Everything Deepl翻译 Node版本控制nvm-windows

其他

如果你在DOTA2自定义游戏制作过程中遇到了任何问题，可以到本项目的 Issues页面 提问，如果我知道的将会予以解答。

X-Template

Xavier's dota2 custom game development template (English translated with DeepL)

Pre-requisites

If you want to use this template, in addition to mastering the Valve's development tools, you need to additionally learn

1. the syntax of typescript, javascript
2. the basics of react
3. the basics of node.js
4. learn about react-panorama
5. learn about TypeScriptToLua
6. learn about the DOTA2 Typescript API, you can check out node_modules/dota-lua-types and node_modules/panorama-types after you finish yarn.

Supported features

1. convert the xlsx, xls kv files into a kv file and put it in the game/scripts/npc,
2. convert addon.csv to addon_*.txt, (also you can convert them back to addon.csv),
3. convert kv files to json files for you to fetch kv data in panorama UI,
4. use typescript to write game logic and panorama UI in content/panorama/src and game/scripts/src.

• please check gulpfile.ts for more details.

Supported commands

1. yarn launch [[addon_name] map_name] launches dota2, all parameters are optional, if addon_name is provided then the specified addon will be loaded (default to launch this project), if map_name is provided then the corresponding map name will be loaded automatically (if addon_name is not provided then the current addon will be loaded by default)
2. yarn dev enter dev mode to compile the ts source code and watch the changes of the files.
3. yarn prod to run publish operation, it will automatically generate publish folder and automatically link to dota_addons/you_addon_name_publish folder, then you can choose this folder to publish (you can set some settings for publishing in package.json -> dota_ developer to make some settings for publishing).
4. yarn compile to compile the source contents

Usage

1. click use this project as a template to generate your own project or fork this project
2. install node.js, require above Node v14.10.1 ~~ because versions below is not tested ~~
3. clone the generated or fork project
4. open package.json and change name to your preferred name
5. execute yarn to install the dependencies, it should automatically link content,game folder to your dota 2 beta/dota_addons/your_preferred_name, (if you encounter permission problems, please try to restart)
6. yarn dev and start your development

Contents

• content is synchronized with dota 2 beta/content/dota_addons/your_addon_name
• game is synchronized with dota 2 beta/game/dota_addons/your_addon_name
• shared to write some shared declarations used in panorama and typescript-to-lua, like custom net tables
• excels to edit kv tables
• localization to write localization files
• scripts contains some helper scripts

1. if you need encryption, please check scripts/publish.js
2. feel free to submit issues
3. contributions are welcome

Acknowledgements

• ModDota Community
• React-panorama is developed by https://github.com/ark120202
• Some of the code is from https://github.com/MODDOTA/TypeScriptAddonTemplate

x-template's Issues

无法正常运行

安装成功之后 npm run dev，kv_2_js报错。求大佬解答 @XavierCHN

TS2584: Cannot find name 'console'. Do you need to change your target library?

After Valve updated the javascript engine I got multiple errors regarding eval ... Function(...).

Updated my package to match yours and removed the plugin from webpack.dev.

Now i recieve:
ERROR in content/panorama/src/utils/x-nettable-dispatcher.ts:110:9
TS2584: Cannot find name 'console'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'.
108 | }
109 | } catch (error) {

110 | console.log(x_net_table dispatch error: ${table_name} -> ${key} -> ${content});
| ^^^^^^^
111 | }
112 | }
113 |

Seems like the original panorama polyfill is missing?

编译的时候顺序是随机的？

webpack.config.js 文件中 PanoramaManifestPlugin 函数下，的目录不写就不编译，写了也不会按顺序编译？每个xml的前后顺序是随机的？

CustomGameEventManager类函数泛型推断问题

node_modules@moddota\dota-lua-types\types\api.generated.d.ts中，
对 CustomGameEventManager.Send_ServerToAllClients等函数进行了参数类型定义，
例：
Send_ServerToAllClients<T extends string | object>(
eventName: (T extends string ? T : string) | keyof CustomGameEventDeclarations,
eventData: CCustomGameEventManager.InferEventType<T, never>,
): void;
我发现传入参数的过程对类型泛型T产生了污染，
保持上述定义方式时：

这里出现的never很诡异，输入的参数是object类型，理应在体操中不产生never类型
进行测试，将
eventData: CCustomGameEventManager.InferEventType<T, never>,
的泛型直接改成
eventData: T
这时的报错非常诡异：

由此 推测泛型T在第一个参数推断时受到了污染，尝试多定义一个泛型U对参数分别进行类型推断：
Send_ServerToAllClients<T,U extends string | object>(
eventName: (T extends string ? T : string) | keyof CustomGameEventDeclarations,
eventData: CCustomGameEventManager.InferEventType<U, never>,
): void;
报错解除

或者有其他更好的方法？

npm i 报错

会导致游戏闪退的情况集合

这个帖子用来收集dota2自定义游戏开发过程中，会导致游戏直接闪退的情况

yarn dev 后出现如下报错

报错处代码：

去掉“content.table_name != null”后报错解除
我猜测content.table_name == null的情况通过了第一个if？所以会出现{ table_name: string; key: string; content: any; }这种类型的变量content，然后进行.split

纯新手，可能是我少安装了什么环境，python用的是3.10.9，nodejs按照说明中安装，lua还没有安装

关于用less还是scss的问题

你好 目前的框架是用less来生成css文件
如果我还想用scss来渲染组件的画 需要修改哪些东西 或者去哪个版本参考

yarn install 报错`C:\Program Files (x86)\MSBuild\14.0\bin\MSBuild.exe` failed with exit code: 1

moddota中关于useState的用例不能显示ToggleButton Slider组件问题

目前我用modedota官方的例子 按钮和滑块都不显示 只能显示相关的text
比如ToggleButton组件
<ToggleButton
text="Show details"
selected={showDetails}
onactivate={() => setShowDetails(!showDetails)}
/>

在游戏界面进入没有button可以点击 只能点击Show details文字 然后显示 showDetails

关于 `npm run launch`

1. argv 里加入 -console 会导致 panorama 不再编译到 game 文件夹中，非本项目相关，好奇。
2. npm 更新后，将不再支持 process.env.npm_config_argv 的写法，详见 https://github.com/npm/rfcs/blob/latest/implemented/0021-reduce-lifecycle-script-environment.md

yarn dev报错

content/panorama/webpack.dev.js 的原本的webpack-panorama 好像得改成新的 webpack-panorama-x

XState吞错

Action内部出错时,错误会被吞了

修复: 文件xstate-dota.ts 行开始196

const executeStateActions = <
    TContext extends object,
    TEvent extends EventObject = any,
    TState extends Typestate<TContext> = { value: any; context: TContext }
>(
    state: StateMachine.State<TContext, TEvent, TState>,
    event: TEvent | InitEvent
) => state.actions.forEach(({ exec }) => {
    if (exec)
    {
        xpcall(exec, debug.traceback, undefined,state.context, event);
    }
});

npm run dev 时报错

error TSTL: Could not resolve lua source files for require path 'bit' in file src\utils\sha.lua.

新手 一个关于UI的问题

一般写模块UI都分很多个文件夹，把不同模块的UI都写在不同的文件夹中 在简单编写后我尝试把他们都声明在webpack.config 配置PanoramaManifestPlugin的入口中（entry） 完成编译后 控制台输出No issues found 没有任何报错 我查看过layout/custom文件夹和custom_ui_manifest文件，我觉得自动生成的代码和路径都没有错（生成的内容应该都没有问题）
但是启动map之后 位置在子文件夹的ui模块没有生效（已经声明在PanoramaManifestPlugin） 然后我尝试把子文件夹的代码移到父目录（src/hud/）重新编译 代码生成的位置改变后，就神奇的生效了。（我尝试过把父目录的声明在PanoramaManifestPlugin注释掉也没有办法让子目录的模块UI生效）
如此一来 我该如何让子文件夹的ui模块生效呢？（例如 src/hud/ ... / ... ）
在反复调试过程中 我发现是子目录的样式文件没有直接产生作用（查看过xml文件，样式文件引用路径没有错）
如果删除掉所有东西 在子目录写一个很简单的模块UI（例如 src/hud/ ... / ... ） 然后在PanoramaManifestPlugin声明它（type：hud） 编译后自动生成代码没有报错的情况下 游戏是不会显示任何自定义UI的，即便是一个很简单的Label标签 一句hello world 因为样式表没有起作用 所以什么都看不见 但将代码（就是tsx xml less三个文件）原封不动的移动到他的父目录（src/hud/），PanoramaManifestPlugin声明改到父目录路径，UI就正常显示 样式表正常生效。
父目录的tsx文件导入调用子目录的模块ui没有问题，但是子目录的模块UI依然没有被同级的样式表less所影响 直接被父目录的样式表影响，意味着子目录的样式表失效，如果不解决这个问题，哪怕我依然能逃课实现一些UI功能，我需要把所有的样式都集中写在父目录的一个或者多个样式表中 否则因为样式失效，UI会出现问题。
纯新手 dota2地图编辑 如果大佬有空的话帮我解答一下 谢谢！

1.0版本的panorama不会自动更新

1.0框架，使用npm run dev后，更改react代码，dota2界面不会自动更新，

关于自己重写官方监听事件的问题

/**当物品被拾取时触发 */
dota_item_picked_up(event:GameEventProvidedProperties & DotaItemPickedUpEvent){
print("dota_item_picked_up")
const item = EntIndexToHScript(event.ItemEntityIndex) as CDOTA_Item /**转化成实例 */
print(item.GetName())
item.RemoveSelf()

}
/**注册官方事件 */
registerofficialEvent(){
    print("registerofficialEvent")
    ListenToGameEvent("dota_item_picked_up",(event)=>this.dota_item_picked_up(event),null)

}

我这么写 每次在控制台输入dota_create_item item_ballista 创建一个弩炮 应该走进我自己写的dota_item_picked_up函数中，但是现在确穿在了英雄身上并没有走进我的dota_item_picked_up函数，
("registerofficialEvent")这条log是可以打出来的 说明我注册成功了，请问是不是还应该设置一些什么？

node版本

现在找不到node 15 了,官网上只有node 16.15.1,可以用不?

为什么本地调试没问题，一发到游廊上地图都打不开

无论是自己的图，还是直接用x大的框架按照说明发布的空项目

游廊上都会有这个错误，寻找服务器之后直接返回房间了

能够实现修改dota自走棋的ui界面么

大佬，你好。

我看现在网络上的教程一般都是如何编写开发自己的地图，
想问一下，能否修改已有的rpg地图的ui，如dota自走棋这种，在棋子选择面板可以展示剩余的棋子数量等等这种功能。我在github上找到了另外一个项目:auto-chess-ui-mode，按照他的流程走了一下，但是没有效果，也不清楚是因为他项目过时的问题，还是我哪里没有配置对。

另外还想问一下这种行为是否被允许。

不管是否回答，都先感谢作者！！

node-gyp could not use PowerShell to find Visual Studio 2017 or newer

CustomGameEventManager这个类 没有了呀 还发现了几个

我可能是好久没用了
今天使用发现我自己在src里写的main.ts CustomGameEventManager这个类调用不了了
还有CDOTAPlayer好像也木有了

现在使用有什么注意事项吗 我看在xnet-table.ts中还可以调用

请问一下，能从游戏内存中拿到秘钥嘛？

最近才开始接触dota2，请教几个问题
dota2的lua引擎某个函数可能被hook掉嘛，作弊者能从中拿到数据吗？
一般使用GetTableValue拿到数据，有可能会被以上作弊手段拿到吗？

Excel to KV 报错：herolist.txt is duplicated

描述：
之前正常使用中，某个时间编辑完Excel后yarn dev 时报错
已尝试更新 gulp-dotax 到1.1.14版本，无效。

请问这是什么问题导致的？如何解决？谢谢

这是第二次在这一步出现问题报错，第一次出现问题后重装框架解决。