Skip to content

Latest commit

 

History

History
230 lines (179 loc) · 9.66 KB

Part1.md

File metadata and controls

230 lines (179 loc) · 9.66 KB
Raw

Part 1.编写你的第一个插件​

本章你将学到：

  • 安装TShock插件模板
  • 使用Rider创建插件项目
  • 初步了解编写一个插件的流程

1.安装TShock插件模板 (by @xuyuwtu)

  1. 打开一个PowerShell
    image
  2. 复制并且运行以下命令
dotnet new install TShock.Plugin.ProjectTemplates

看到如下提示即安装成功
image

2.新建TShock插件项目

  1. 回到Rider，点击新建解决方案 image
  2. 按照下图填写，然后点击创建 image

Note

一般来讲，项目名只由字母(A-Z,a-z)，数字(0-9)，下划线(_)组成，并且项目名具有实际意义

不要使用中文！不要使用中文！不要使用中文！(引自棱镜)​

Tip

解决方案中可以包含多个插件项目。使用同一个解决方案存放多个插件项目可以方便管理多个插件代码，并且方便项目之间互相引用。

注: 如果提示没有按照目标框架，点击提示安装即可。

2.进入项目项目​

资源管理器(右上角)

它是一个非常重要的工具窗口,它可以用来管理、操作你的项目中的各个文件。其中Plugin.cs就是你插件的源码文件，我们双击就可以打开它。 image

Tip

如果哪一天资源管理器不见了，你可以在主菜单(左上角Rider图标旁的四条横线)-视图-工具窗口-资源管理器找到它 image

Tip

如果你觉得文件名字不顺眼，那么你可以从资源管理器重命名这个文件 当然同样要遵循命名规范，不随意使用中文 image

3.开始编写代码​

这里有个简单的TShock插件示例，你可以复制替换到Plugin.cs

using System.Reflection;
using Terraria;
using TerrariaApi.Server;
using TShockAPI;

namespace MyFirstPlugin;

[ApiVersion(2, 1)]
public class Plugin : TerrariaPlugin 
{
    
    //插件的名称
    public override string Name => "MyFirstPlugin";
    
    //插件作者名字
    public override string Author => "You Name";
    
    //插件功能的一句话描述
    public override string Description => "Plugin Description"; 

    //插件的版本, 可以采用日期来命名, eg: 2024年1月4日第1个版本 -> new(2024, 1,4,1)
    public override Version Version => new(2024, 1,4,1);
    
    //插件的构造器
    public Plugin(Main game) : base(game) 
    {
    }

    //插件加载时执行的代码
    public override void Initialize()
    {
        /*
        添加一个TShock命令,下面这句的意思是: (看不懂没关系，下面有专门的章节讲解命令)
        添加一个命令: 权限为`plugin.perm`,执行这条命令时调用`HelloWorldCommand`方法,命令的名字是`helloworld`,别名是`hw`
        */
        Commands.ChatCommands.Add(new Command("plugin.perm" , HelloWorldCommand, "helloworld", "hw"));
    }
        
    //插件卸载时执行的代码
    protected override void Dispose(bool disposing)
    {
        if (disposing)
        {
            //移除所有由本插件添加的所有指令
            var asm = Assembly.GetExecutingAssembly();
            Commands.ChatCommands.RemoveAll(c => c.CommandDelegate.Method?.DeclaringType?.Assembly == asm);
        }
        base.Dispose(disposing);
    }

    //执行指令时对指令进行处理的方法
    private void HelloWorldCommand(CommandArgs args)
    {
        //向触发事件的玩家发送一条绿色的消息 "Hello world!"
        args.Player.SendSuccessMessage("Hello world!");
    }
}

粘贴代码后，左下角的错误数是0，恭喜你可以开始构建插件了

Note

如果有错误存在，可能是你复制漏了某些地方 也可能是你的环境有问题

5.构建你的插件​

点击工具栏处(右上角)的锤子即可开始构建 image

6.找到并安装你的插件​

  1. 在资源管理器右键当前项目(Myfirstplugin),选择打开于-资源管理器 image

  2. 此时会弹出你的项目文件夹，顺着bin/Debug/net6.0就能找到你的插件啦~

image

Note

文件的作用:
.dll: 插件的本体
.pdb: 调试文件, 放在ServerPlugins文件夹和插件一起加载, 报错时会显示报错方法对应源代码的具体位置

  1. 然后把插件的.dll文件和.pdb文件复制到TShock的ServerPlugins文件夹就可以开始调试啦~

Tip

可以像Cai把TShockPlugins文件夹固定在快速访问，这样就可以很快的把插件替换上去啦~ image

  1. 为什么要安装PDB (看不懂可以先忽略)
    我们下面有段代码,会在插件加载时报错
29   public void KoKoLoveYou()
30   {
        //抛出错误，模拟报错 :(
31      throw new Exception("别做梦了Cai");
32   }
33   
34   //插件加载时执行的代码
35   public override void Initialize()
36   {
37      if ("Cai"=="SB") //Cai不是SB, 所以KoKoLoveYou不会在这里被执行
38      {
39          KoKoLoveYou();
40      }
41  
42      if (1 + 1 == 2) //1+1=2 所以KoKoLoveYou在这里被执行
43      {
44          KoKoLoveYou();
45      }
46  }

  • 如果你没有安装PDB那么你看到的报错是这样的 image

    从报错我们可以知道，在调用插件的Initialize方法时，KoKoLoveYou方法报错。此时我们回到源代码，发现Initialize方法中有两个KoKoLoveYou，所以就会出现找不到具体报错位置的情况(实际情况肯定不是向上面例子一样你一眼就能看出来哪里有问题的)

  • 如果我们安装了PDB image 此时，报错的调用栈就会告诉我们报错方法对应代码的具体位置，这里我们看到Initialize在第44行报错，对应我们代码的第二个KoKoLoveYou方法，这样报错的位置就被轻松找到了

7.测试你的插件​

  1. 启动TShock, 可以看到你的第一个插件已经加载成功了 image

  2. 使用/help命令查看命令列表，可以发现插件添加的命令已经在命令列表中显示 (这里装了Help Plus) image

  3. 执行/helloworld(或者/hw)，控制台打印出绿色Hello world!说明插件功能正常
    image

8.使用VBY.PluginLoader热重载插件 (by @xuyuwtu)

当我们修改代码后，我们需要把新构建的插件丢进ServerPlugins里，同时还需要重启TShock来重新加载我们的插件，TShock重启的速度很慢，这样很浪费时间，所以我们就可以使用VBY.PluginLoader热重载插件

命令 作用
/load load 加载所有PluginLoader所管理的插件
/load unload 卸载PluginLoader所管理的插件
/load reload 重载PluginLoader所管理的插件
/load plugins 显示PluginLoader已加载的插件
  1. 使用前你必须删除ServerPlugins中你需要热重载的插件
    image
  2. 安装VBY.PluginLoader，你可以在TShock中文插件库找到这个插件
    image
  3. 安装并加载后你的TShock根目录下会多出一个PluginLoader文件夹, 我们把插件丢进去
    image
    image
  4. 此时使用命令/hw,发现插件已经被VBY.PluginLoader加载。如果弹出两个, 说明你没有删除原插件文件夹的插件
    image
  5. 我们这时候修改一下我们的代码，然后重新构建 
    //执行指令时对指令进行处理的方法
private void HelloWorldCommand(CommandArgs args)
{
    //显示 “Hello 玩家的名字!”
    args.Player.SendSuccessMessage($"Hello {args.Player.Name}!");
}
  6. 把文件替换到PluginLoader文件夹
    image
  7. 执行命令/load reload
    image
  8. 此时我们再执行/hw,就会出现我们修改过的结果啦~
    image

Note

控制台也算是玩家(TSPlayer.Server)，它的名字是Server