ZXland API 接口

v1.0.0

ZXland 领地系统提供完整的领地管理 API，支持 C++ 和 Python 两种语言接入。

Python 超简单

Python 插件只需 1 个文件 land_api.py 即可调用所有领地 API！

📋 接口列表

领地查询

方法	参数	返回值	说明
`isInLand`	`x, y, z, dim`	`bool`	检查坐标是否在领地内
`getLandNameAt`	`x, y, z, dim`	`string`	获取坐标所在领地名
`getLandAt`	`x, y, z, dim`	`LandData*`	获取坐标所在领地详情
`getLandByName`	`name`	`LandData*`	根据名称获取领地

权限查询

方法	参数	返回值	说明
`hasPermission`	`player, landName, perm`	`bool`	检查玩家在领地的权限
`hasPermissionAt`	`player, x, y, z, dim, perm`	`bool`	检查玩家在坐标的权限
`getPlayerRole`	`landName, player`	`string`	获取玩家在领地的角色
`getFlag`	`landName, flag, role`	`bool`	获取领地权限标志

成员管理

方法	参数	返回值	说明
`getLandMembers`	`landName`	`vector`	获取领地成员列表

领地列表

方法	参数	返回值	说明
`getPlayerLands`	`player`	`vector`	获取玩家拥有的领地
`getAllLands`	-	`vector`	获取所有领地

领地工具

方法	参数	返回值	说明
`getLandArea`	`landName`	`int64`	获取领地面积(方块数)
`isLandOwner`	`landName, player`	`bool`	判断玩家是否为领地主人
`getTeleportPos`	`landName`	`TeleportPos`	获取领地传送点

防护罩

方法	参数	返回值	说明
`isShieldEnabled`	`landName`	`bool`	检查防护罩是否启用
`isShieldPurchased`	`landName`	`bool`	检查防护罩是否已购买
`setShieldEnabled`	`landName, enabled`	`bool`	设置防护罩状态 (仅C++)

领地管理 (仅C++)

方法	参数	返回值	说明
`createLand`	`LandData`	`bool`	创建领地
`deleteLand`	`name`	`bool`	删除领地
`addMember`	`landName, player, role`	`bool`	添加成员
`removeMember`	`landName, player`	`bool`	移除成员
`setFlag`	`landName, flag, value, role`	`bool`	设置权限标志
`transferLand`	`landName, newOwner`	`bool`	转让领地
`renameLand`	`oldName, newName`	`bool`	重命名领地
`setLandWelcomeMsg`	`landName, msg`	`bool`	设置欢迎消息
`setLandLeaveMsg`	`landName, msg`	`bool`	设置离开消息
`setTeleportPos`	`landName, x, y, z`	`bool`	设置传送点

Python API 是只读的

Python API 只能查询数据，不能修改领地。如需修改领地，请使用 C++ API。

数据结构

LandData - 领地数据

字段	类型	说明
name	string	领地名称
owner	string	领地主人
dim	int	维度 (0=主世界, 1=下界, 2=末地)
x1, y1, z1	float	起点坐标
x2, y2, z2	float	终点坐标
is3d	bool	是否3D领地
flyEnabled	bool	飞行是否启用
flyPurchased	bool	飞行是否已购买
shieldEnabled	bool	防护罩是否启用
shieldPurchased	bool	防护罩是否已购买
teleportPos	TeleportPos	传送点位置
welcomeMsg	string	欢迎消息
leaveMsg	string	离开消息

TeleportPos - 传送点

字段	类型	说明
x	float	X坐标
y	float	Y坐标
z	float	Z坐标
isSet	bool	是否已设置

LandMember - 领地成员

字段	类型	说明
player	string	玩家名称
role	string	角色 (owner/member/guest)

领地查询接口

isInLand - 检查是否在领地内

检查指定坐标是否位于任何领地内。

参数	类型	说明
x	float	X坐标
y	float	Y坐标
z	float	Z坐标
dim	int	维度

返回值	类型	说明
inLand	bool	是否在领地内

C++Python

cpp

bool inLand = service->isInLand(100.0, 64.0, 100.0, 0);
if (inLand) {
    player->sendMessage("你在领地内！");
}

python

in_land = land.is_in_land(100.0, 64.0, 100.0, 0)
if in_land:
    player.send_message("你在领地内！")

getLandNameAt - 获取领地名称

获取指定坐标所在的领地名称。

参数	类型	说明
x	float	X坐标
y	float	Y坐标
z	float	Z坐标
dim	int	维度

返回值	类型	说明
name	string	领地名，不在领地则返回空字符串

C++Python

cpp

std::string landName = service->getLandNameAt(x, y, z, dim);
if (!landName.empty()) {
    player->sendMessage("当前领地: " + landName);
}

python

land_name = land.get_land_name_at(x, y, z, dim)
if land_name:
    player.send_message(f"当前领地: {land_name}")

getLandAt - 获取领地详情

获取指定坐标所在的领地完整信息。

参数	类型	说明
x	float	X坐标
y	float	Y坐标
z	float	Z坐标
dim	int	维度

返回值	类型	说明
land	LandData*	领地数据，不在领地则返回nullptr

C++Python

cpp

LandData* land = service->getLandAt(x, y, z, dim);
if (land) {
    player->sendMessage("领地: " + land->name);
    player->sendMessage("主人: " + land->owner);
    player->sendMessage("范围: (" + std::to_string((int)land->x1) + "," + 
                        std::to_string((int)land->z1) + ") ~ (" +
                        std::to_string((int)land->x2) + "," + 
                        std::to_string((int)land->z2) + ")");
}

python

land_data = land.get_land_at(x, y, z, dim)
if land_data:
    player.send_message(f"领地: {land_data.name}")
    player.send_message(f"主人: {land_data.owner}")
    player.send_message(f"范围: ({int(land_data.x1)},{int(land_data.z1)}) ~ ({int(land_data.x2)},{int(land_data.z2)})")

权限查询接口

hasPermission - 检查领地权限

检查玩家在指定领地是否有特定权限。

参数	类型	说明
player	string	玩家名称
landName	string	领地名称
perm	string	权限名 (build/break/use/attack 等)

返回值	类型	说明
hasPerm	bool	是否有权限

C++Python

cpp

bool canBuild = service->hasPermission("Steve", "我的领地", "build");
if (canBuild) {
    // 允许建造
}

python

can_build = land.has_permission("Steve", "我的领地", "build")
if can_build:
    # 允许建造

hasPermissionAt - 检查坐标权限

检查玩家在指定坐标是否有特定权限（自动查找领地）。

参数	类型	说明
player	string	玩家名称
x	float	X坐标
y	float	Y坐标
z	float	Z坐标
dim	int	维度
perm	string	权限名

返回值	类型	说明
hasPerm	bool	是否有权限（不在领地内返回true）

C++Python

cpp

bool canBuild = service->hasPermissionAt("Steve", x, y, z, dim, "build");
if (!canBuild) {
    player->sendMessage("§c你没有在这里建造的权限！");
    event.setCancelled(true);
}

python

can_build = land.has_permission_at("Steve", x, y, z, dim, "build")
if not can_build:
    player.send_message("§c你没有在这里建造的权限！")
    event.cancelled = True

getPlayerRole - 获取玩家角色

获取玩家在领地中的角色。

参数	类型	说明
landName	string	领地名称
player	string	玩家名称

返回值	类型	说明
role	string	角色：owner/member/guest，空字符串表示访客

C++Python

cpp

std::string role = service->getPlayerRole("我的领地", "Steve");
if (role == "owner") {
    player->sendMessage("你是领地主人！");
} else if (role == "member") {
    player->sendMessage("你是领地成员");
} else {
    player->sendMessage("你是访客");
}

python

role = land.get_player_role("我的领地", "Steve")
if role == "owner":
    player.send_message("你是领地主人！")
elif role == "member":
    player.send_message("你是领地成员")
else:
    player.send_message("你是访客")

getFlag - 获取权限标志

获取领地的权限标志设置。

参数	类型	说明
landName	string	领地名称
flag	string	标志名 (explosion/pvp/mob_spawn 等)
role	string	角色（可选）

返回值	类型	说明
value	bool	标志值

C++Python

cpp

bool allowExplosion = service->getFlag("我的领地", "explosion", "");
if (!allowExplosion) {
    // 阻止爆炸
}

python

allow_explosion = land.get_flag("我的领地", "explosion", "")
if not allow_explosion:
    # 阻止爆炸

成员管理接口

getLandMembers - 获取领地成员

获取领地的所有成员列表。

参数	类型	说明
landName	string	领地名称

返回值	类型	说明
members	`vector<LandMember>`	成员列表

C++Python

cpp

auto members = service->getLandMembers("我的领地");
for (auto &m : members) {
    player->sendMessage(m.player + " - " + m.role);
}

python

members = land.get_land_members("我的领地")
for m in members:
    player.send_message(f"{m.player} - {m.role}")

领地工具接口

getLandArea - 获取领地面积

获取领地的面积（方块数）。

参数	类型	说明
landName	string	领地名称

返回值	类型	说明
area	int64	领地面积(方块数)

C++Python

cpp

int64_t area = service->getLandArea("我的领地");
player->sendMessage("领地面积: " + std::to_string(area) + " 格");

python

area = land.get_land_area("我的领地")
player.send_message(f"领地面积: {area} 格")

isLandOwner - 判断是否为主人

判断玩家是否为领地主人。

参数	类型	说明
landName	string	领地名称
player	string	玩家名称

返回值	类型	说明
isOwner	bool	是否为主人

C++Python

cpp

bool isOwner = service->isLandOwner("我的领地", "Steve");
if (isOwner) {
    player->sendMessage("你是领地主人！");
}

python

is_owner = land.is_land_owner("我的领地", "Steve")
if is_owner:
    player.send_message("你是领地主人！")

getTeleportPos - 获取传送点

获取领地的传送点坐标。

参数	类型	说明
landName	string	领地名称

返回值	类型	说明
pos	TeleportPos	传送点信息

C++Python

cpp

auto tp = service->getTeleportPos("我的领地");
if (tp.isSet) {
    player->sendMessage("传送点: (" + std::to_string((int)tp.x) + "," + 
                        std::to_string((int)tp.y) + "," + 
                        std::to_string((int)tp.z) + ")");
}

python

tp = land.get_teleport_pos("我的领地")
if tp and tp.is_set:
    player.send_message(f"传送点: ({int(tp.x)},{int(tp.y)},{int(tp.z)})")

领地列表接口

getPlayerLands - 获取玩家领地

获取玩家拥有的所有领地。

参数	类型	说明
player	string	玩家名称

返回值	类型	说明
lands	`vector<LandData>`	领地列表

C++Python

cpp

auto lands = service->getPlayerLands("Steve");
player->sendMessage("你拥有 " + std::to_string(lands.size()) + " 块领地");
for (auto &l : lands) {
    player->sendMessage(" - " + l.name);
}

python

lands = land.get_player_lands("Steve")
player.send_message(f"你拥有 {len(lands)} 块领地")
for l in lands:
    player.send_message(f" - {l.name}")

getAllLands - 获取所有领地

获取服务器上的所有领地。

返回值	类型	说明
lands	`vector<LandData>`	所有领地列表

C++Python

cpp

auto allLands = service->getAllLands();
player->sendMessage("服务器共有 " + std::to_string(allLands.size()) + " 块领地");

python

all_lands = land.get_all_lands()
player.send_message(f"服务器共有 {len(all_lands)} 块领地")

防护罩接口

isShieldEnabled - 防护罩是否启用

检查领地防护罩是否启用。

参数	类型	说明
landName	string	领地名称

返回值	类型	说明
enabled	bool	是否启用

C++Python

cpp

bool shieldOn = service->isShieldEnabled("我的领地");
if (shieldOn) {
    player->sendMessage("防护罩已启用！");
}

python

shield_on = land.is_shield_enabled("我的领地")
if shield_on:
    player.send_message("防护罩已启用！")

isShieldPurchased - 防护罩是否已购买

检查领地是否已购买防护罩。

参数	类型	说明
landName	string	领地名称

返回值	类型	说明
purchased	bool	是否已购买

C++Python

cpp

bool hasBought = service->isShieldPurchased("我的领地");
if (!hasBought) {
    player->sendMessage("你还没有购买防护罩！");
}

python

has_bought = land.is_shield_purchased("我的领地")
if not has_bought:
    player.send_message("你还没有购买防护罩！")

完整示例：保护插件

C++ 建造保护示例Python 建造保护示例

cpp

#include "land_api.h"

void onBlockPlace(BlockPlaceEvent &event) {
    auto service = getServer().getServiceManager().load<ILandService>("LandService");
    if (!service) return;
    
    auto &player = event.getPlayer();
    auto &block = event.getBlock();
    float x = block.getX();
    float y = block.getY();
    float z = block.getZ();
    int dim = player.getDimension().getType();
    
    if (!service->hasPermissionAt(player.getName(), x, y, z, dim, "build")) {
        player.sendMessage("§c你没有在这个领地建造的权限！");
        event.setCancelled(true);
    }
}

python

from land_api import LandAPI

class ProtectionPlugin(Plugin):
    def on_enable(self):
        self.land = LandAPI(self)
        
    def on_block_place(self, event):
        player = event.player
        block = event.block
        x, y, z = block.x, block.y, block.z
        dim = player.location.dimension.type.value
        
        if not self.land.has_permission_at(player.name, x, y, z, dim, "build"):
            player.send_message("§c你没有在这个领地建造的权限！")
            event.cancelled = True

C++ 接入方式

方式一：ServiceManager（推荐）

cpp

#include <endstone/plugin/plugin.h>
#include "land_api.h"

class MyPlugin : public endstone::Plugin {
public:
    void onEnable() override {
        auto service = getServer().getServiceManager().load<ILandService>("LandService");
        if (service) {
            getLogger().info("ZXland API 加载成功！");
        }
    }
};

头文件

将 land_api.h 复制到你的项目 include 目录。

Python 接入方式

直接数据库连接（推荐）

Python API 直接连接 ZXland 的 SQLite 数据库，无需额外依赖。

python

from land_api import LandAPI

class MyPlugin(Plugin):
    def on_enable(self):
        self.land = LandAPI(self)
        
        if self.land.is_connected():
            self.logger.info("ZXland API 连接成功！")

工作原理

Python 插件 → LandAPI → SQLite数据库 (lands.db)

注意

Python API 是只读的，只能查询数据，不能修改领地。如需修改领地，请使用游戏内命令或 C++ API。

📥 下载 API 文件

C++ 开发

land_api.h - C++ 接口头文件

Python 开发

land_api.py - Python API 文件（只需这 1 个！）

插件下载

endstone_zxland.dll - ZXland 领地插件

超级简单

Python 开发者只需下载 land_api.py 一个文件，无需任何额外依赖！

ZXland API 接口 ​

📋 接口列表 ​

领地查询 ​

权限查询 ​

成员管理 ​

领地列表 ​

领地工具 ​

防护罩 ​

领地管理 (仅C++) ​

数据结构 ​

LandData - 领地数据 ​

TeleportPos - 传送点 ​

LandMember - 领地成员 ​

领地查询接口 ​

isInLand - 检查是否在领地内 ​

getLandNameAt - 获取领地名称 ​

getLandAt - 获取领地详情 ​

权限查询接口 ​

hasPermission - 检查领地权限 ​

hasPermissionAt - 检查坐标权限 ​

getPlayerRole - 获取玩家角色 ​

getFlag - 获取权限标志 ​

成员管理接口 ​

getLandMembers - 获取领地成员 ​

领地工具接口 ​

getLandArea - 获取领地面积 ​

isLandOwner - 判断是否为主人 ​

getTeleportPos - 获取传送点 ​

领地列表接口 ​

getPlayerLands - 获取玩家领地 ​

getAllLands - 获取所有领地 ​

防护罩接口 ​

isShieldEnabled - 防护罩是否启用 ​

isShieldPurchased - 防护罩是否已购买 ​

完整示例：保护插件 ​

C++ 接入方式 ​

方式一：ServiceManager（推荐） ​

头文件 ​

Python 接入方式 ​

直接数据库连接（推荐） ​

工作原理 ​

📥 下载 API 文件 ​

C++ 开发 ​

Python 开发 ​

插件下载 ​

ZXland API 接口

📋 接口列表

领地查询

权限查询

成员管理

领地列表

领地工具

防护罩

领地管理 (仅C++)

数据结构

LandData - 领地数据

TeleportPos - 传送点

LandMember - 领地成员

领地查询接口

isInLand - 检查是否在领地内

getLandNameAt - 获取领地名称

getLandAt - 获取领地详情

权限查询接口

hasPermission - 检查领地权限

hasPermissionAt - 检查坐标权限

getPlayerRole - 获取玩家角色

getFlag - 获取权限标志

成员管理接口

getLandMembers - 获取领地成员

领地工具接口

getLandArea - 获取领地面积

isLandOwner - 判断是否为主人

getTeleportPos - 获取传送点

领地列表接口

getPlayerLands - 获取玩家领地

getAllLands - 获取所有领地

防护罩接口

isShieldEnabled - 防护罩是否启用

isShieldPurchased - 防护罩是否已购买

完整示例：保护插件

C++ 接入方式

方式一：ServiceManager（推荐）

头文件

Python 接入方式

直接数据库连接（推荐）

工作原理

📥 下载 API 文件

C++ 开发

Python 开发

插件下载