【后端接口】buildguild 与 getmyguild：行会接口的创建与归属查询

实战应用：用在哪里

行会系统的接口对：buildguild 处理创建，getmyguild 查询归属，行会的建立、成员的行会身份查询、行会维度的业务分发全在这两个接口上展开。行会接口的调用者通常是后台管理脚本与行会功能脚本两类。

创建接口

---创建行会 actor:会长对象 name:行会名
function buildguild(actor, name) end

-- GM 后台：代为建会
function gmBuildGuild(plrName, guildName)
    local actor = getplayerbyname(plrName)
    if not actor then return false, "玩家不在线" end
    if getmyguild(actor) ~= nil then return false, "已有行会" end
    buildguild(actor, guildName)
    sendmsg(actor, 1, "行会「" .. guildName .. "」创建成功")
    return true
end

创建接口的会长参数即行会的创始会长，行会的第一批数据（会长、创建时间、名字）在接口内部建档。getmyguild 查询玩家所属行会，无行会返回空值，行会维度的业务（仓库、频道、任务）都以这个查询作为权限的第一道闸。

归属查询与成员遍历

-- 行会广播：遍历在线成员
function guildBroadcast(guildName, text)
    local members = getguildmembers(guildName)
    for _, name in ipairs(members) do
        local actor = getplayerbyname(name)
        if actor then
            sendmsg(actor, 1, "【行会】" .. text)
        end
    end
end

成员遍历加在线过滤是行会广播的标准写法，离线成员走邮件通道补偿。行会维度的变量（行会基金、等级）与成员维度的变量（贡献）分两套接口管理，setguildvar 管行会的、setplayvar 管成员的，两套数据的权限边界清晰。行会的创建在游戏内还有道具与费用门槛，后台接口的创建绕过门槛直接建档，管理便利与游戏规则的边界要明确。

验证与监控

行会创建与解散的流水统计，行会数量的增长曲线是社交生态的健康指标。

踩坑记录

buildguild 的重名校验曾经依赖游戏内入口的检查，后台直接调接口建同名行会成功，数据层出现了两个同名行会，唯一性校验下沉到接口层后根治。getmyguild 的返回值在行会解散瞬间的时序问题：解散触发时成员的归属查询还返回旧行会，解散流程的成员清空顺序调整后一致。

上线要点

行会接口的调用权限要收敛：buildguild 只允许后台管理脚本与游戏内的创建流程调用，业务脚本随意建会的口子要封死。行会名同样走敏感词与格式校验，后台创建不豁免。成员遍历的性能在千人行会上是可感知的，广播类操作考虑批量接口或异部分批处理。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。