SC服务端插件接口文档

发表于 2026-06-20 阅读次数：

本文档以当前源码为准，整理服务端插件开发时常用的生命周期、加载规则、命令接口、事件接口与注册方式。所有服务端插件代码需要在 SERVER 构建中使用，常见命名空间包括：

using Game.Server;
using Game.Server.Event;
using Game.Server.PlayerEvent;
using Game.Server.Terminal;
using Engine;

插件加载规则

插件基类为 Game.Server.ServerPlugin。

public abstract class ServerPlugin
{
    public abstract int Version { get; }
    public abstract string Name { get; }
    public abstract void Initialize();
    public abstract void Load();
    public abstract void Save();
    public virtual void Update(float dt) { }
}

外部插件 DLL 放在服务端插件目录 Plugins 下，由 ServerManager.LoadPluginsDll() 扫描。
DLL 中所有继承 ServerPlugin 且非抽象的类会被实例化。
DLL 中所有继承 AbstractProcessCmd 且非抽象的命令类会自动注册到 CmdManager。
内置插件和外部插件都会执行 Initialize()；世界加载后执行 Load()，保存时执行 Save()，服务端每帧执行 Update(dt)。
事件订阅建议放在 Initialize()，避免 Load() 多次执行导致重复订阅。
插件配置建议存到 Storage.GetSystemPath("app:/Configs") 或当前世界目录，避免写入程序目录失败。

最小插件示例

using Game.Server;

namespace MyPlugin;

public class HelloPlugin : ServerPlugin
{
    public override int Version => 10000; // 1.0.0
    public override string Name => "示例插件";

    public override void Initialize()
    {
    }

    public override void Load()
    {
    }

    public override void Save()
    {
    }

    public override void Update(float dt)
    {
    }
}

事件注册约定

大多数事件都有对应的 XxxEventManager.AddObject(this) 和 RemoveObject(this)：

public override void Initialize()
{
    MessageEventManager.AddObject(this);
    PlayerEnterGameEventManager.AddObject(this);
}

返回值约定：

多数 bool 返回值表示是否允许原行为继续执行。
返回 false 通常表示拦截、取消或禁止该行为。
管理器一般会遍历所有处理器，只要任意处理器返回 false，最终结果就是 false。
FirstLevel 多数接口暂未完整实现排序，建议默认返回 0。

消息与告示牌接口

IMessageEventHandle

命名空间：Game.Server.Event

该接口保持旧插件兼容，告示牌相关插件应继续实现此接口。

public interface IMessageEventHandle
{
    byte FirstLevel { get; }

    void ReceiveMessage(
        string playerName,
        NetNode netNode,
        Client From,
        string message,
        byte messageType,
        out bool External);

    bool EditSignMessage(Point3 point, ComponentPlayer componentPlayer);
}

说明：

ReceiveMessage 在服务端收到聊天消息时触发。
External 用于标记外部消息显示样式；旧插件可继续使用。
EditSignMessage 在玩家请求编辑告示牌时触发，返回 false 可阻止打开编辑界面。
当前版本为了兼容旧插件，IMessageEventHandle 不再使用 ref string message，也不再把告示牌接口改成 void。

示例：

public class SignGuardPlugin : ServerPlugin, IMessageEventHandle
{
    public override int Version => 10000;
    public override string Name => "告示牌保护";
    public byte FirstLevel => 0;

    public override void Initialize()
    {
        MessageEventManager.AddObject(this);
    }

    public bool EditSignMessage(Point3 point, ComponentPlayer componentPlayer)
    {
        return componentPlayer != null;
    }

    public void ReceiveMessage(string playerName, NetNode netNode, Client From, string message, byte messageType, out bool External)
    {
        External = false;
    }

    public override void Load() { }
    public override void Save() { }
}

IMutableMessageEventHandle

命名空间：Game.Server.Event

新插件如果需要修改玩家聊天内容，可以额外实现该扩展接口。它不会替代 IMessageEventHandle。

public interface IMutableMessageEventHandle
{
    void ReceiveMessage(
        string playerName,
        NetNode netNode,
        Client From,
        ref string message,
        byte messageType);
}

示例：

public class WordReplacePlugin : ServerPlugin, IMessageEventHandle, IMutableMessageEventHandle
{
    public override int Version => 10000;
    public override string Name => "聊天替换";
    public byte FirstLevel => 0;

    public override void Initialize()
    {
        MessageEventManager.AddObject(this);
    }

    public void ReceiveMessage(string playerName, NetNode netNode, Client From, string message, byte messageType, out bool External)
    {
        External = false;
    }

    public void ReceiveMessage(string playerName, NetNode netNode, Client From, ref string message, byte messageType)
    {
        message = message.Replace("bad", "***");
    }

    public bool EditSignMessage(Point3 point, ComponentPlayer componentPlayer) => true;
    public override void Load() { }
    public override void Save() { }
}

玩家连接与验证接口

IBanEventHandle

命名空间：Game.Server

public interface IBanEventHandle
{
    byte FirstLevel { get; }

    bool IsBan(
        string nickname,
        string id,
        string password,
        string ip,
        NetNode netNode,
        Client client,
        out bool UseExternalPassword);

    bool IsBanIp(string ip, NetNode netNode, ConnectionRequest request);
}

IsBan 返回 true 表示拒绝玩家进入。
UseExternalPassword 可告知后续密码验证走外部逻辑。
IsBanIp 返回 true 表示按 IP 拒绝连接。

1	BanEventManager.AddObject(this);

IPasswordValidationEventHandle

命名空间：Game.Server.Event

public interface IPasswordValidationEventHandle
{
    byte FirstLevel { get; }

    bool ValidatePassword(
        string inputPassword,
        string serverPassword,
        bool useExternalPassword,
        string nickname,
        string communityAccountId,
        string ipAddress,
        NetNode netNode,
        Client client,
        out string errorMessage);
}

用于自定义密码验证。
返回值表示验证是否通过。
errorMessage 会作为失败提示。

1	PasswordValidationEventManager.AddObject(this);