主题
ZXland Python 接入指南
v1.0.0本指南详细介绍如何在 Python 插件中使用 ZXland 领地 API。
无需下载
ZXland 启动时自动生成 Python API 模块，直接 import 使用！
快速开始
1. 声明依赖
python
class MyPlugin(Plugin):
api_version = "0.10"
depend = ["zxland"]2. 在 on_enable 中导入并初始化
python
from endstone.plugin import Plugin
class MyPlugin(Plugin):
api_version = "0.10"
depend = ["zxland"]
def on_enable(self):
from land_api import LandAPI
self.land = LandAPI(self)
if self.land.is_connected():
self.logger.info("ZXland API 连接成功！")重要
必须在 on_enable() 内 import，不能在文件顶部 import！因为 API 模块在 ZXland 启动后才会生成。
常用 API 示例
检查玩家是否在领地内
python
in_land = self.land.is_in_land(x, y, z, dim)
if in_land:
land_name = self.land.get_land_name_at(x, y, z, dim)
player.send_message(f"你在领地 {land_name} 内")获取领地详情
python
land = self.land.get_land_at(x, y, z, dim)
if land:
player.send_message(f"领地: {land.name}")
player.send_message(f"主人: {land.owner}")
area = self.land.get_land_area(land.name)
player.send_message(f"面积: {area} 格")检查玩家权限
python
can_build = self.land.has_permission("Steve", "我的领地", "build")
can_break = self.land.has_permission("Steve", "我的领地", "break")
can_use = self.land.has_permission("Steve", "我的领地", "use")获取玩家角色
python
role = self.land.get_player_role("我的领地", "Steve")
if role == "owner":
# 是领地主人
elif role == "member":
# 是领地成员
else:
# 是访客获取玩家所有领地
python
lands = self.land.get_player_lands("Steve")
player.send_message(f"你拥有 {len(lands)} 块领地")
for l in lands:
player.send_message(f" - {l.name}")获取所有领地
python
all_lands = self.land.get_all_lands()
player.send_message(f"服务器共有 {len(all_lands)} 块领地")获取领地传送点
python
tp = self.land.get_teleport_pos("我的领地")
if tp and tp.is_set:
player.send_message(f"传送点: {tp.x}, {tp.y}, {tp.z}")API 方法一览
| 方法 | 返回值 | 说明 |
|---|---|---|
is_connected() | bool | 检查数据库连接 |
is_in_land(x, y, z, dim) | bool | 是否在领地内 |
get_land_name_at(x, y, z, dim) | str | 获取领地名 |
get_land_at(x, y, z, dim) | LandData | 获取坐标处领地 |
get_land_by_name(name) | LandData | 获取领地详情 |
has_permission(player, land, perm) | bool | 检查权限 |
has_permission_at(player, x, y, z, dim, perm) | bool | 检查坐标权限 |
get_player_role(land, player) | str | 获取玩家角色 |
get_player_lands(player) | list | 获取玩家领地 |
get_all_lands() | list | 获取所有领地 |
get_land_members(land) | list | 获取领地成员 |
get_flag(land, flag, role) | bool | 获取标志 |
is_shield_enabled(land) | bool | 护盾状态 |
get_land_area(land) | int | 领地面积 |
is_land_owner(land, player) | bool | 是否主人 |
get_teleport_pos(land) | TeleportPos | 获取传送点 |
数据类型
LandData
python
@dataclass
class LandData:
id: int
name: str
owner: str
dim: int
x1, y1, z1: float
x2, y2, z2: float
is3d: bool
welcome_msg: str
leave_msg: str
fly_enabled: bool
fly_purchased: bool
shield_enabled: bool
shield_purchased: bool
teleport_pos: TeleportPosTeleportPos
python
@dataclass
class TeleportPos:
x: float
y: float
z: float
is_set: bool注意事项
必须声明依赖
你的插件必须添加 depend = ["zxland"]，确保 ZXland 先加载并生成 API 模块。
import 位置
必须在 on_enable() 内 import，不能在文件顶部！
只读 API
Python API 只能读取数据，不能修改领地。如需修改，请使用游戏内命令或 C++ API。