模组开发指南
学习如何使用 tModLoader 的 C# API 创建精彩的 Terraria 模组
20 分钟阅读
开发
中级
前置条件
开发环境
- • Visual Studio 2022（推荐）
- • JetBrains Rider
- • Visual Studio Code 配合 C# 扩展
- • .NET 6.0 SDK 或更高版本
知识要求
- • 基础 C# 编程
- • 面向对象概念
- • 熟悉 Terraria 游戏玩法
- • 基本的游戏开发理解
开发环境设置
基本模组结构
每个 tModLoader 模组都遵循标准结构：
YourModName/
├── build.txt # 模组元数据和依赖项
├── description.txt # 浏览器中的模组描述
├── icon.png # 模组图标（推荐 64x64）
├── YourModName.cs # 主模组类
├── Items/ # 自定义物品
├── NPCs/ # 自定义 NPC
├── Projectiles/ # 自定义弹幕
├── Tiles/ # 自定义图块/方块
├── Walls/ # 自定义墙壁
├── Buffs/ # 自定义增益/减益
└── Sounds/ # 自定义音频文件示例模组类
以下是基本的模组类结构：
using Terraria.ModLoader;
namespace YourModName
{
public class YourModName : Mod
{
public override void PostSetupContent()
{
// Code that runs after all mods are loaded
}
public override void PostUpdateInput()
{
// Code that runs every frame
}
public override void Unload()
{
// Cleanup code when mod is unloaded
}
}
}build.txt 配置
build.txt 文件包含关于你的模组的重要元数据：
displayName = Your Mod Name
author = Your Name
version = 1.0.0
modReferences =
buildIgnore = *.csproj, *.user, *.suo, bin/, obj/, .vs/
homepage = https://github.com/yourusername/yourmod
description = A brief description of what your mod does创建你的第一个物品
让我们创建一把简单的自定义剑作为你的第一个物品：
创建物品类
创建一个新文件：Items/ExampleSword.cs
using Terraria;
using Terraria.ID;
using Terraria.ModLoader;
namespace YourModName.Items
{
public class ExampleSword : ModItem
{
public override void SetDefaults()
{
// Basic item properties
Item.damage = 50;
Item.DamageType = DamageClass.Melee;
Item.width = 40;
Item.height = 40;
Item.useTime = 20;
Item.useAnimation = 20;
Item.useStyle = ItemUseStyleID.Swing;
Item.knockBack = 6;
Item.value = Item.buyPrice(gold: 1);
Item.rare = ItemRarityID.Green;
Item.UseSound = SoundID.Item1;
Item.autoReuse = true;
}
public override void AddRecipes()
{
Recipe recipe = CreateRecipe();
recipe.AddIngredient(ItemID.IronBar, 10);
recipe.AddIngredient(ItemID.Wood, 5);
recipe.AddTile(TileID.Anvils);
recipe.Register();
}
}
}添加物品纹理
创建一个 40x40 像素的 PNG 图片并保存为：
Items/ExampleSword.png
文件名必须与你的类名完全匹配。
构建和测试你的模组
构建 + 重载工作流
tModLoader 强大的开发功能允许你即时测试更改：
- 在 tModLoader 中，前往"创意工坊" → "开发模组"
- 在列表中找到你的模组，点击"构建 + 重载"
- 等待编译完成
- 你的模组将自动重载并应用更改
- 在游戏中测试你的新物品
小贴士：在开发过程中频繁使用"构建 + 重载"。这比重启游戏快得多！
常见构建错误
- 缺少纹理：确保 PNG 文件与类名完全匹配
- 编译错误：检查语法和 using 语句
- 缺少引用：验证 ModLoader 引用是否正确
- Build.txt 错误：检查模组元数据格式
高级开发主题
发布你的模组
发布到 Steam Workshop
- 确保你的模组构建没有错误
- 前往"创意工坊" → "开发模组"
- 点击你的模组旁边的"发布"
- 填写 Steam Workshop 表单，包括描述和标签
- 上传截图并设置可见性
- 点击"发布"使其上线
发布后几分钟内，你的模组将在模组浏览器中可用。
发布最佳实践
内容准则
- 编写清晰详细的描述
- 包含高质量截图
- 发布前进行充分测试
- 记录已知问题
技术要求
- 没有编译错误或警告
- 正确的空值检查
- 多人联机兼容性测试
- 性能优化