1-初识模组

[!TIP]
这一节我们学习模组类型、模组工具安装、工具教程，下一节再细讲模组。

[!CAUTION]
本教程仅适合新手，不适合进阶，进阶看视频流量，欢迎关注哔哩哔哩账号：复古物语中文社区

一、初识模组

复古物语有三种类别的模组，每种模组的复杂程度各不相同：

1. 内容模组（Content Mod）：主要用 JSON 改物品、方块、配方等。可以仅JSON实现内容添加的模组，比如物品添加、物品特性等。
2. 代码模组（Code Mod）：不能单纯依靠 JSON 实现的模组，必须添加 C# 代码去实现功能，比如我制作的 简单语音模组
3. 主题包（Theme Pack）：主要改外观、字体、界面风格。

官方维基提醒你：

[!TIP]
如果你是新手，最好先从内容模组入手，因为大多数代码模组只是扩展内容模组中方块、物品和实体的功能。一旦你掌握了内容模组，就可以开始学习编程，为你的《Vintage Story》游戏体验添加一些真正特别的内容。
更高级的程序员可能会忍不住直接跳到代码修改，但我们仍然强烈建议您先熟悉内容修改，因为您几乎肯定会将它们与您编写的任何 C# 代码一起使用。

二、工具和环境

这里我们讲解两个工具的安装部署过程：Visual Studio Code 和 Visual Studio

[!TIP]
我认为这两个工具都必不可少，特别是Visaul Studio，这是一款免费且功能强大的开发环境，也是《Vintage Story》团队用于游戏开发的工具。

1、下载Visual Studio

下载地址：https://visualstudio.microsoft.com/zh-hans/downloads/

1. 点击下载即可
   
2. 点击安装：
3. 按照图片选择：
   
   这里我推荐C盘位置不变（你也可以修改其他盘），我们需要选中的有：工作负载|.NET桌面开发、语言包|中文（简体），其他可以默认不改动，大约7G内存，右下角点击安装即可（左边下拉无所谓，如果在高铁等地点网络不好建议：全部下载后再安装）

插播一个我的编程启蒙老师的哔哩哔哩视频（看到9分14秒即可）：

[!WARNING]
设置模组模板包需要插入这里讲。

4. 设置模组模板包

[!TIP]
官方 Wiki 的做法是安装 Vintage Story 的模组模板，然后用 dotnet new 创建项目。

[details="示例命令"]

dotnet new install <template>
dotnet new <template> -n MyFirstMod

[/details]

我们使用下面命令安装（模板来自官方Github仓库）：

dotnet new install VintageStory.Mod.Templates

安装结果：

Windows PowerShell
Copyright (C) Microsoft Corporation. All rights reserved.

Install the latest PowerShell for new features and improvements! https://aka.ms/PSWindows

PS C:\Users\29596> dotnet new install VintageStory.Mod.Templates
将安装以下模板包:
   VintageStory.Mod.Templates

成功: VintageStory.Mod.Templates@1.22.0 已安装以下模板:
模板名                             短名称    语言  标记
---------------------------------  --------  ----  -------------------
Vintage Story Mod                  vsmod     [C#]  Games/Vintage Story
Vintage Story Mod (code/dll only)  vsmoddll  [C#]  Games/Vintage Story

PS C:\Users\29596>

5. 启动后页面：选择常规、深色（浅色容易招Bug）
   
6. 右边选择创建新项目

[!TIP]
这里我们就可以看到VintageStory的模板项目。如果搜索不到，说明你上面 设置模组模板包 没有做。

2、下载Visual Studio Code

下载地址：https://code.visualstudio.com/

安装过程看哔哩哔哩视频，本教程就不细讲了，默认配置即可。

需要添加中文语言，按照图片添加即可。

[!WARNING]
Visual Studio Code 需要单独安装 .NET SDK，因为 VS Code 本身只是一个轻量级代码编辑器，不包含 .NET 编译器和运行时。

3、安装 .NET SDK

[!TIP]
如果你先安装了Visual Studio，那么安装后应该存在.NET SDK

下载地址：https://dotnet.microsoft.com/zh-cn/download

确认命令行能运行：

dotnet --list-sdks

三、了解资源系统

开始制作你的第一个模组时，首先要做的是熟悉资源系统。这正是 Vintage Story 大部分功能得以实现的地方，在进行模组制作时，你会不断用到这些资源。

一般Windows电脑在你安装游戏的位置，你也可以重新安装一次在开发项目的文件夹，然后不卸载旧安装位置，下面是我游戏安装位置（D:\Vintagestory）

[details="重新安装一次在开发项目的文件夹，然后不卸载旧安装位置"]
[wrap=color color=red bgcolor=transparent]选否NO，不卸载旧安装位置[/wrap]
[/details]

D:\Vintagestory\assets 文件夹包含三个文件夹：“creative”、“game”和“survival”

这三个本质上是 Vintage Story 自带的三个资源域，可以理解成三个内置模组：

• assets/game是基础层。
  这里放的是全游戏共用的核心资源，比如 lang、fonts、shaders、sounds、基础 textures/shapes/entities/blocktypes。界面、字体、通用贴图、底层实体和很多公共定义都在这里。没有它，游戏基本跑不起来。
• assets/survival是生存模式层。
  这里有 recipes、patches、worldgen、worldproperties、itemtypes、blocktypes 等，主要负责生存模式里的配方、进度、世界生成、物品方块、声音贴图这些内容。你平时玩到的大多数“正式游戏内容”，基本都在这里。
• assets/creative是创造模式层。
  它也有 blocktypes、itemtypes、dialog、textures、worldgen 等，但规模比 survival 小，主要偏创造模式、调试/辅助内容，给创造玩法提供额外资源支持。

简单记的话：

game = 基础框架
survival = 正常生存内容
creative = 创造模式内容

四、了解模组目录

一共有两个支持模组加载的目录，推荐 %APPDATA%\VintagestoryData\Mods

1. %APPDATA%\VintagestoryData\Mods
2. 安装路径\Mods

五、学习方法

每次只做一个小功能，比如：

• 先做一个新物品。
• 再做一个新方块。
• 再做一个简单配方。
• 最后再写 C# 代码。

这样最稳，也最容易排错。

六、注意事项

• 不要直接改游戏安装目录里的原文件。
• 所有自定义内容都放在你自己的 Mod 目录里。
• 遇到不确定的东西，优先用“复制 vanilla 文件到 Mod，再改”的方式学习。

参考资料

1. Modding:Getting Started - Vintage Story Wiki官方维基入门指南，介绍模组类型（Theme Packs、Content Mods、Code Mods）、JSON基础、资产系统。
2. Modding:Developing a Content Mod - Vintage Story Wiki详细内容模组开发教程，包括IDE选择、modinfo.json设置、文件夹结构、Mod Domains、打包发布等。
3. Vintage Story: The "How To" Modding Tutorial Series | Part1 - Setup
4. Programming a mod for Vintage Story start to finish!
5. Modding Vintage Story 播放列表
6. Modding:Content Tutorial Simple Recipe - Vintage Story Wiki简单配方教程，教你为物品和方块创建网格配方，包含资产下载和完整示例。
7. Vintage Story Modding - JSON and ShapesJSON和自定义形状模组制作
8. Modding:Setting up your Development Environment - Vintage Story Wiki开发环境设置指南（注意可能有更新，推荐查看最新模板）。
9. anegostudios/vsmodexamples (GitHub)
   官方示例模组仓库，包含内容模组和代码模组示例。
10. API文档C#代码模组参考文档，配合维基使用。