简单脚本

SimpleScripting - Hytale 服务端 JavaScript 脚本模组

此版本已废弃，请使用最新版本：https://www.curseforge.com/hytale/mods/simplescripting

如有问题或需要帮助，请加入我们的 Discord：Discord

源代码：HostTale-Project/SimpleScripting

用 JavaScript 脚本释放 Hytale 服务器的全部潜力！

SimpleScripting 是一款强大的插件，为 Hytale 服务器带来了服务端 JavaScript 脚本能力。您可以创建自定义命令、处理玩家事件、构建复杂功能并扩展服务器功能，全程无需编写一行 Java 代码。

---

为什么选择 SimpleScripting？

无需 Java 基础 - 使用全球最流行的编程语言之一 JavaScript 编写脚本。只要掌握基础 JavaScript，您就能创建服务器功能。

热重载 - 修改脚本后无需重启服务器即可立即重新加载，非常适合快速开发和测试。

开箱即用 - 随附一整套针对常见服务器功能（如家园、传送点、传送请求等）的示例脚本！

完全可扩展 - 全面的 API 让您能够访问玩家、世界、事件、命令、权限、数据库和调度器。

---

主要特性

自定义命令

轻松创建自己的命令！支持：

• 必需和可选参数（字符串、整数、双精度浮点数）
• 命令别名
• Tab 补全
• 权限要求
• 带颜色的富文本格式化

事件系统

响应服务器上的一切事件：

• 玩家加入/退出 - 欢迎消息、登录奖励
• 玩家死亡/重生 - 死亡消息、重生处理
• 玩家聊天 - 聊天格式化、过滤、自定义聊天功能
• 玩家移动 - 区域检测、边界强制
• 世界变化 - 追踪跨维度玩家
• 命令执行 - 命令记录、拦截
• 服务器刻 - 周期性任务、自动化

传送 API

安全可靠的传送功能，具备：

• 异步区块预加载（不会崩溃！）
• 传送预热计时器
• 位置和旋转支持
• 跨世界传送

数据库 API

简单而强大的键值存储：

• 自动持久化保存为 JSON 文件
• 按玩家数据存储
• 服务器全局数据存储
• 无需外部数据库

调度器 API

按需运行任务：

• 延时执行（按刻或毫秒）
• 重复任务
• 任务取消
• 非常适合冷却、预热和周期性事件

权限 API

与 Hytale 原生权限系统集成：

• 检查玩家权限
• 命令权限要求
• 管理员检测
• 为您的脚本自定义权限节点

---

附带的示例脚本

SimpleScripting 附带了 8 个可直接使用的脚本，您可以立即启用：

家园系统 (homes.js)

让玩家设置并传送到个人家园位置。

• /sethome [名称] - 设置家园位置
• /home [名称] - 传送到家园
• /delhome <名称> - 删除家园
• /homes - 列出所有家园
• 可根据玩家等级配置家园数量上限！

传送点系统 (warps.js)

服务器全局传送点，方便导航。

• /setwarp <名称> - 创建服务器传送点（管理员）
• /warp <名称> - 传送到传送点
• /delwarp <名称> - 删除传送点（管理员）
• /warps - 列出可用传送点

出生点系统 (spawn.js)

中心出生点管理。

• /setspawn - 设置服务器出生点（管理员）
• /spawn - 传送到出生点

传送请求 (tpa.js)

安全的玩家间传送。

• /tpa <玩家> - 请求传送到某玩家处
• /tpahere <玩家> - 请求某玩家传送到你处
• /tpaccept - 接受传入请求
• /tpdeny - 拒绝传入请求
• /tpcancel - 取消发出的请求
• 可配置超时和冷却时间！

返回命令 (back.js)

返回到之前的位置。

• /back - 返回到你的最后位置
• 死亡时自动保存位置，再也不怕丢物品！
• 可配置历史记录数量

随机传送 (rtp.js)

安全探索世界。

• /rtp - 传送到随机安全位置
• /wild、/randomtp - 别名
• 可配置最小/最大距离
• 自动安全位置检测

等级系统 (ranks.js)

基础等级管理。

• /rank set <玩家> <等级> - 分配等级
• /rank get <玩家> - 查看玩家等级
• /rank list - 列出所有等级
• /myrank - 查看自己的等级

管理员工具 (admin.js)

必备的管理命令。

• /simplescripting reload - 热重载所有脚本
• /simplescripting info - 插件信息
• /tp <玩家> - 传送到某玩家处
• /tphere <玩家> - 让某玩家传送到你处
• /playerinfo <玩家> - 查看玩家详情
• /players - 列出在线玩家

---

配置

所有设置都可轻松在 lib/config.js 中自定义：

var DEFAULTS = {
    homes: {
        maxHomes: 3,
        cooldownSeconds: 5,
        warmupSeconds: 3
    },
    warps: {
        cooldownSeconds: 5,
        warmupSeconds: 3
    },
    tpa: {
        timeoutSeconds: 60,
        cooldownSeconds: 10,
        warmupSeconds: 3
    },
    rtp: {
        minDistance: 100,
        maxDistance: 5000,
        cooldownSeconds: 300
    }
    // ... 更多！
};

基于等级的配置

为不同玩家等级定义不同限制：

var RANKS = {
    default: {
        // 使用默认设置
    },
    vip: {
        homes: { maxHomes: 5, cooldownSeconds: 3 }
    },
    admin: {
        homes: { maxHomes: 10, cooldownSeconds: 0 }
    }
};

---

面向开发者

综合 API

SimpleScripting 提供以下访问权限：

API	描述
Commands	注册带参数和权限的自定义命令
Events	监听玩家和服务器事件
Players	查找、管理和获取玩家信息
Worlds	访问世界数据和方块信息
Teleport	带异步区块加载的安全传送
DB	键值数据库存储
Scheduler	延时和重复任务
Permissions	权限检查和需求
MessageHelper	发送消息和广播
Colors	Minecraft 颜色代码和格式化
Logger	控制台日志记录

示例：创建自定义命令

Commands.register()
    .setName('greet')
    .setDescription('问候一名玩家')
    .addRequiredStringArg('player', '要问候的玩家')
    .setHandler(function(ctx) {
        var target = Players.getByNameFuzzy(ctx.getArgAsString('player'));
        if (target) {
            MessageHelper.send(target, Colors.GOLD + '来自 ' + Players.getUsername(ctx.getPlayer()) + ' 的问候！');
            ctx.sendMessage(Colors.GREEN + '问候已发送！');
        } else {
            ctx.sendMessage(Colors.RED + '未找到玩家！');
        }
    });

示例：监听事件

Events.on('playerJoin', function(event) {
    var player = Players.getByUuid(event.playerUuid);
    MessageHelper.broadcast(Colors.YELLOW + Players.getUsername(player) + ' 已加入服务器！');
});

Events.on('playerDeath', function(event) {
    var player = Players.getByUuid(event.playerUuid);
    var loc = Players.getFullLocation(player);
    // 保存死亡位置供 /back 命令使用
    DB.save('death_locations', event.playerUuid, JSON.stringify(loc));
});

工具库

附带的 lib/utils.js 提供了实用函数：

• Utils.getPlayerFromContext(ctx) - 从命令上下文中获取玩家
• Utils.formatTime(seconds) - 格式化时间间隔
• Utils.formatPosition(x, y, z) - 格式化坐标
• Utils.createCooldownTracker() - 简易冷却管理
• Utils.teleportWithWarmup() - 带倒计时的传送

---

目录结构

universe/SimpleScripting/
├── mods/                    # 您的 JavaScript 文件
│   ├── lib/                 # 共享库（优先加载）
│   │   ├── utils.js         # 通用工具
│   │   └── config.js        # 配置
│   ├── homes.js             # 家园系统
│   ├── warps.js             # 传送点系统
│   └── ...                  # 您的自定义脚本！
├── db/                      # 数据库文件（自动创建）
└── assets/                  # 资源文件夹（开发中 - 暂不可用）
    ├── config/              # 配置文件
    ├── lang/                # 语言文件
    └── ui/                  # UI 定义

---

安装

1. 下载插件 JAR 文件
2. 将其放入服务器的 plugins 文件夹
3. 启动服务器
4. 插件会自动创建 universe/SimpleScripting/mods/ 目录
5. 示例脚本会自动复制
6. 根据您的喜好自定义脚本！

---

更新脚本

只需编辑 .js 文件并运行 /simplescripting reload - 无需重启服务器！

---

支持与社区

发现 Bug？有功能请求？想分享您的脚本？

• 在我们的问题追踪器上报告问题
• 公共仓库即将开放，您可以通过提交 Pull Request 贡献代码