YAS货币

YAS货币

YASCurrency是一款原生的Hytale经济与钱包系统，支持数字余额、实体货币、交易记录、管理工具、API接口、多语言用户界面，并提供可选的商店与服务器经济系统集成功能。

游戏玩法

YAS货币预览查看大图

YASCurrency

YASCurrency 是一个原生的 Hytale 货币、钱包、现金、HUD、交易、存储和经济控制系统，专为服务器设计。

它集成了数字玩家余额、沉浸式实体现金物品、可配置钱包、玩家 HUD、交易历史、QuestLines 支持、VaultUnlocked 支持、商店集成支持、多语言 UI、可选的 MariaDB 存储、存储诊断、迁移工具以及一个面向开发者的公共 API，构成了一个完整的经济基础。

重大经济控制更新：
YASCurrency 不再只是一个货币插件。它现在是一个完整的服务器经济管理系统，包含交易监控、手续费与税收处理、回滚工具、来源封锁、玩家账户检查、现金/数字货币追踪、通胀控制选项、奖励缩放、可选的 MariaDB 支持、存储诊断、迁移工具，以及用于结构化集成的 API v4。

无论你是运营一个简单的服务器经济、一个角色扮演现金系统、一个任务驱动的 RPG 服务器、一个商店网络、一个玩家市场，还是一个带有多个插件的复杂经济体系，YASCurrency 都能为你提供监控、管理、保护、存储、迁移和扩展资金流动所需的工具。

文档：
API 与最终用户文档：https://api-yas-currency.web.app/

重大更新：经济控制

本次更新在现有的 YASCurrency 钱包、现金、HUD 和交易系统之上，增加了一层完整的经济控制功能。

  • 交易监控 针对数字经济和现金经济活动的监控。
  • 经济仪表板 用于查看货币创造、货币销毁、转账、警告和总供应量。
  • 管理员交易日志 支持过滤、玩家查询、来源检查和交易详情。
  • 回滚支持 通过创建安全的冲正交易而不是删除账本历史来实现。
  • 来源与外部 ID 封锁 用于阻止可疑或不需要的交易流。
  • 按玩家账户检查 包含玩家特定的交易历史。
  • 玩家账户历史分页 在管理员账户工具内实现。
  • 可配置的手续费和税收 适用于转账、商店、PlayerShops、现金、QuestLines 奖励和 Claim 付款。
  • 可选的通胀控制 包含可配置的每日铸币上限和大额交易警告。
  • 可选的动态奖励缩放 用于高级服务器经济平衡。
  • 存储诊断 用于检查当前后端、健康状况、账户数量、交易数量和总货币供应量。
  • API v4 提供结构化的交易上下文、费用策略、预览和结果对象。

简单的服务器可以保持高级控制功能禁用，将 YASCurrency 用作一个干净的钱包和现金系统。更大的服务器则可以在需要更深层次控制时启用监控、限制、费用、MariaDB 存储、存储诊断、迁移工具和高级经济控制。

新特性：可选的 MariaDB 存储后端

YASCurrency 现在支持 MariaDB 作为可选的存储后端，与默认的 SQLite 存储并存。

SQLite 仍是大多数单服务器设置的默认和推荐存储选项。 现有的服务器可以继续使用 SQLite，无需任何外部数据库设置或迁移。

MariaDB 适用于大型服务器、托管环境、外部数据库管理，或者偏好将经济数据存储在专用数据库服务器中的管理员。

  • SQLite 仍然是默认后端，不需要外部数据库。
  • 可以手动启用 MariaDB，通过 YASCurrency 配置文件。
  • 支持自动创建表，当 MariaDB 数据库已存在时。
  • 存储诊断 帮助管理员验证当前哪个后端处于活动状态。
  • 支持从 SQLite 迁移到 MariaDB，通过一个明确的管理员命令。
  • 迁移后不会自动切换后端，让管理员完全掌控。

这使得 YASCurrency 对于简单的本地服务器设置和大型生产环境都具有灵活性。

存储设置：SQLite 或 MariaDB

YASCurrency 可以使用 SQLite 或 MariaDB 运行。

默认 SQLite 存储

SQLite 是默认的存储后端。它简单、可靠，不需要外部数据库服务器。

storage.type=sqlite
storage.file=yascurrency.sqlite

这是大多数小型和单服务器安装的推荐设置。

可选的 MariaDB 存储

对于大型或外部托管的服务器设置，可以手动启用 MariaDB。

storage.type=mariadb
mariadb.host=localhost
mariadb.port=3306
mariadb.database=yascurrency
mariadb.username=yascurrency
mariadb.password=change-me
mariadb.useSsl=false
mariadb.connectionTimeoutMs=5000
mariadb.autoCreateTables=true

MariaDB 数据库和数据库用户必须由服务器管理员创建。当启用 mariadb.autoCreateTables=true 时，YASCurrency 可以在已有数据库内创建所需的表。

MariaDB 准备示例

CREATE DATABASE yascurrency
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

CREATE USER 'yascurrency'@'localhost' IDENTIFIED BY 'your_password';

GRANT ALL PRIVILEGES ON yascurrency.* TO 'yascurrency'@'localhost';

FLUSH PRIVILEGES;

存储诊断

管理员可以通过以下命令验证活动后端和存储健康状态：

/yascurrency storage test
/yascurrency storage status

诊断信息显示活动后端、存储描述、健康状态、账户数量、交易数量和总货币供应量。

从 SQLite 迁移到 MariaDB

YASCurrency 包含一个明确的迁移命令，用于从 SQLite 迁移到 MariaDB：

/yascurrency storage migrate sqlite-to-mariadb

迁移命令会：

  • 检查当前是否为 SQLite 活动状态。
  • 在导入数据前创建 SQLite 备份。
  • 初始化 MariaDB 目标架构。
  • 复制账户、交易和元数据。
  • 拒绝将数据导入到已包含 YASCurrency 数据的 MariaDB 数据库中。
  • 迁移后比较账户数量、交易数量和总货币供应量。
  • 报告迁移完成状态是 OK 还是 WARNING。

重要提示： 迁移后 YASCurrency 不会自动切换到 MariaDB。成功迁移后，请手动在配置文件中设置 storage.type=mariadb 并重启服务器。

主要特性

  • 原生 Hytale UI 使用游戏内自定义 UI 页面。
  • 数字玩家余额 用于基于账户的服务器货币。
  • 实体现金支持 用于沉浸式现金风格的经济设置。
  • 默认 SQLite 存储 提供简单可靠的服务器设置。
  • 可选的 MariaDB 存储后端 用于大型服务器和外部数据库管理。
  • 存储诊断命令 用于检查后端状态、健康状况、账户数量、交易数量和总货币供应量。
  • 从 SQLite 到 MariaDB 的迁移命令 包含备份、导入和比较检查。
  • 可配置的钱包 UI 玩家可查看余额、现金信息、交易历史和 HUD 设置。
  • 余额 HUD 包含每个玩家的位置、偏移量、显示选项、图标和可选择的背景。
  • 交易历史 支持收入和支出过滤。
  • 过滤后的交易总计 便于追踪收入和支出款项。
  • 管理员工具 用于管理余额、检查交易、配置现金、维护经济、审查资金流动、检查存储健康和运行迁移。
  • 新玩家起始余额支持。
  • 可配置的货币名称、符号、标签和可选的符号可见性。
  • 玩家转账 具有可配置的限制和交易记录。
  • 现金支付和找零处理 用于实体现金支付。
  • 动态现金物品名称和描述 使用按物品堆叠的显示元数据。
  • QuestLines 集成 支持数字要求、实体现金要求、操作、奖励和文本变量。
  • QuestLines Claims 支持 用于 Claim 购买、租金、续租和可读的经济追踪。
  • VaultUnlocked 支持 用于兼容的经济桥接场景。
  • 多语言支持 包含英语和德语本地化。
  • 公共插件 API v4 供其他模组与余额、现金、费用、预览、交易上下文、HUD 行为和交易历史进行交互。
  • 可选的商店集成支持 适用于诸如 YetAnotherShop 之类的系统。

数字货币

  • 直接在服务器上存储玩家余额。
  • 使用可配置的货币键、显示名称、符号和标签。
  • 可选择完全隐藏货币符号，以实现更清洁的服务器特定经济名称。
  • 支持存款、取款、转账、奖励、付款、更正和管理员调整。
  • 通过交易历史追踪所有相关的余额变化。
  • 使用服务器端验证防止无效、负值或无法负担的交易。
  • 对玩家之间的付款使用可配置的转账限制。
  • 对转账、商店购买、PlayerShop 付款、QuestLines 奖励和 Claim 付款使用手续费和税收。
  • 为商店、任务、奖励、命令、工作、NPC 系统、Claim 和自定义服务器功能提供干净的基础经济系统。

实体现金

  • 在配置了现金物品可用时，支持实体现金风格的付款。
  • 允许服务器基于随身携带的金钱或现金物品创建更沉浸式的经济系统。
  • 可配置的现金档案、显示名称、简称和数值标签。
  • 可配置的现金面额和现金物品价值。
  • 支持现金支付处理与找零处理。
  • 支持存款、取款、现金消费、现金赠予、现金兑换和现金优化。
  • 支持存款和取款流程的特定现金手续费。
  • 现金付款可被兼容的商店、任务或经济集成系统使用。
  • 适用于角色扮演服务器、市场摊位、玩家交易中心、生存经济和实体经济设置。

注意： YASCurrency 控制官方的 YASCurrency 现金流。服务器所有者应确保其他插件不会在支持的经济管道之外创建或复制现金物品。

经济监控与安全

  • 交易监控 默认启用。
  • 监控货币创造、货币销毁、转账、警告和总经济供应量。
  • 审查大额交易和可疑的资金流动。
  • 按玩家、来源、类型、金额、原因和外部 ID 检查交易。
  • 将交易来源作为过滤器打开。
  • 直接从交易中在账户管理标签页打开玩家。
  • 审查玩家特定的交易历史。
  • 使用警告和风险级别更快地识别可疑活动。

该系统旨在帮助服务器所有者了解资金从何处进入经济、从何处流出经济，以及哪些系统负责主要变化。

回滚与封锁工具

  • 回滚 会创建一个安全的冲正交易，而不是删除历史记录。
  • 封锁 可以封锁交易来源或外部 ID。
  • 管理员确认对话框可防止意外执行回滚或封锁操作。
  • 回滚和封锁操作专为经济调查和管理更正而设计。
  • 账本历史保持可追踪，使经济更易于审计。

YASCurrency 不会静默地抹去财务历史。相反，它使交易轨迹保持可理解和可审查。

手续费与税收

YASCurrency 支持针对多种经济流程的可配置手续费和税收。

  • 转账手续费
  • 商店手续费
  • PlayerShop 税
  • 现金取款手续费
  • 现金存款手续费
  • QuestLines 奖励手续费
  • Claim 购买手续费
  • Claim 租金 / 续租手续费

当交易元数据包含手续费信息时，手续费可以在面向玩家的交易历史中显示。这有助于玩家理解为什么一笔付款、奖励、Claim 购买或租金操作会以特定金额改变他们的余额。

通胀控制

YASCurrency 包含可选的通胀控制功能，适用于更大或更复杂的服务器经济。

  • 全局每日货币创造上限。
  • 每个玩家的每日货币创造上限。
  • 大额交易警告阈值。
  • 高每日收益警告阈值。
  • 目标货币供应量值。
  • 奖励缩放最小/最大因子。
  • 可选硬控制模式，用于减少或阻止货币创造。

通胀控制是可选的。想要简单货币设置的服务器可以在保持交易监控激活的同时将其禁用。

钱包与交易历史

  • 玩家可以打开原生钱包 UI 查看当前余额。
  • 钱包显示数字余额、背包中的实体现金、活动现金档案和近期活动。
  • 专用的 HUD 标签页用于玩家特定的余额 HUD 设置。
  • 近期交易以可读的历史列表显示。
  • 收入和支出过滤器帮助玩家了解钱的来源和去向。
  • 过滤后的总计显示所选视图的总收入或总支出。
  • 技术审计条目在面向玩家的正常交易历史中被隐藏。
  • 当来源插件提供结构化的交易原因时，商店交易可以显示更清晰的标签。
  • 当交易包含结构化费用元数据时，手续费可以显示在交易历史中。

管理员工具

  • 检查和玩家管理余额。
  • 为单个玩家打开详细的账户视图。
  • 审查玩家特定的交易历史（带分页）。
  • 通过面向管理员的交易视图审查经济活动。
  • 按玩家、交易 ID、类型、来源、金额、警告、封锁状态或重复项过滤交易。
  • 检查交易详情，例如来源、原因、状态、风险级别、外部 ID 和元数据。
  • 通过安全的冲正交易回滚选中的交易。
  • 封锁可疑来源或外部 ID。
  • 为奖励、更正、测试或服务器管理调整余额。
  • 配置核心经济行为，例如货币标签、起始余额、转账限制和符号可见性。
  • 配置实体现金行为、现金档案名称、现金标签、现金价值和现金操作。
  • 配置数字、现金、商店、QuestLines 和 Claim 流程的手续费和税收。
  • 全局启用或禁用余额 HUD。
  • 使用维护工具进行日志和经济清理任务。
  • 检查活动存储后端和存储健康状态。
  • 在需要时运行从 SQLite 到 MariaDB 的迁移。
  • 旨在帮助服务器所有者维护一个清晰且可管理的经济。

QuestLines 集成

  • YASCurrency 可用于 QuestLines 的要求、操作和文本变量中。
  • 数字余额要求：
    yascurrency:canafford:<金额>
  • 实体现金要求：
    yascurrency:cancashafford:<金额>
  • 数字取款操作：
    yascurrency:take:<金额>:<标签>
  • 实体现金取款操作：
    yascurrency:takecash:<金额>:<标签>
  • 数字余额文本变量：
    {ycurbalance}
  • 实体现金余额文本变量：
    {ycurcashbalance}
  • 当通过结构化的 YASCurrency 经济流程路由时，任务奖励可以使用可配置的奖励手续费。

QuestLines Claims 支持

  • 当兼容的 QuestLines Claims 集成启用时，支持与 Claim 相关的经济流程。
  • Claim 购买可以使用可配置的 Claim 购买手续费。
  • Claim 租金和续租可以使用可配置的 Claim 租金 / 续租手续费。
  • Claim 交易可以在交易日志中显示，包含可读的来源、原因和外部 ID 信息。
  • 管理员工具可以检查、过滤和审查与 Claim 相关的资金流动。

商店与插件集成

  • YASCurrency 为其他模组提供一个 API，用于执行付款、存款、取款、现金检查和余额检查。
  • 兼容的集成可以为玩家历史提供结构化的交易原因，使其更清晰。
  • 支持基于账户的付款和实体现金风格的付款流程（由集成插件实现）。
  • 非常适合用作商店、奖励系统、任务、Claim、服务器工作、NPC 系统和自定义游戏系统的经济后端。
  • YetAnotherShop 可以使用 YASCurrency 进行数字付款、实体现金付款、可读的商店交易历史以及带费用感知的付款预览。

VaultUnlocked 支持

  • VaultUnlocked 可以作为兼容经济场景的桥接工具。
  • VaultUnlocked 是一个合适的模组名称，在管理员 UI 中显示为 VaultUnlocked。
  • 支持可配置的付款和退款模式（如果可用）。
  • 适用于希望 YASCurrency 参与更广泛经济兼容性流程的服务器。

API 与开发者支持

YASCurrency 包含一个面向插件开发者和服务器端集成的公共 API。

  • 公共 API v4 用于余额检查、现金检查、存款、取款、转账、现金消费、现金赠予、预览、结果、HUD 辅助工具、功能标志和交易处理。
  • 功能标志允许集成方检查可用功能。
  • 支持数字余额格式化和实体现金余额格式化。
  • 支持余额 HUD 刷新和玩家 HUD 设置辅助工具。
  • 支持结构化交易原因，以便外部系统传递可读的上下文，例如商店、报价、物品、数量、奖励来源、Claim ID、任务 ID、费用政策或付款原因。
  • 适用于商店、任务、工作、奖励、NPC 系统、Claim、服务器命令和自定义集成。
  • API 和最终用户文档在此处提供：https://api-yas-currency.web.app/

API v4 亮点

  • TransactionContext 用于结构化交易元数据。
  • FeePolicy 用于明确的手续费处理。
  • TransactionPreview 用于在扣款前向玩家显示最终费用。
  • YasCurrencyTransactionResult 用于丰富的成功/失败响应。
  • TransactionStatus 用于更好的集成逻辑。
  • 为存款、取款和转账操作提供了预览方法。
  • 为存款、取款、转账、现金赠予和现金消费操作提供了上下文感知方法。

API v4 的设计使得集成方不再需要仅仅依赖纯文本的原因字符串。相反，他们可以以结构化的方式传递来源、类别、外部 ID、显示原因、元数据和费用政策。

示例：Quest 奖励上下文

TransactionContext ctx = YasCurrencyAPI.questRewardContext(
    questId,
    questName,
    "QuestLines"
);

TransactionPreview preview = YasCurrencyAPI.previewDeposit(playerUuid, rewardAmount, ctx);
YasCurrencyTransactionResult result = YasCurrencyAPI.deposit(playerUuid, rewardAmount, ctx);

示例：Claim 租金上下文

TransactionContext ctx = YasCurrencyAPI.claimRentContext(
    claimId,
    claimName,
    durationDays,
    "QuestLines Claims"
);

TransactionPreview preview = YasCurrencyAPI.previewWithdraw(playerUuid, rentAmount, ctx);
YasCurrencyTransactionResult result = YasCurrencyAPI.withdraw(playerUuid, rentAmount, ctx);

示例：商店购买上下文

TransactionContext ctx = TransactionContext.builder()
    .source("YetAnotherShop")
    .category(TransactionCategory.SHOP_PURCHASE)
    .feePolicy(FeePolicy.SHOP_BUY)
    .externalId(orderId)
    .displayReason("商店购买: " + itemName)
    .metadata("item", itemName)
    .metadata("quantity", String.valueOf(quantity))
    .build();

TransactionPreview preview = YasCurrencyAPI.previewWithdraw(playerUuid, price, ctx);
YasCurrencyTransactionResult result = YasCurrencyAPI.withdraw(playerUuid, price, ctx);

本地化

  • 包含英语和德语语言文件。
  • 可配置的默认语言。
  • 面向玩家的钱包、交易、HUD、QuestLines 和管理员文本在支持的地方已本地化。
  • 专为多语言的 Hytale 服务器设计。
  • 管理员 UI 设计为使用语言文件而不是硬编码的可见 UI 文本。

兼容性说明

  • YASCurrency 可以作为一个独立的经济系统使用。
  • SQLite 作为默认的本地存储后端包含在内。
  • MariaDB 是可选的，需要预先准备好的 MariaDB 数据库和用户。
  • 实体现金功能取决于配置的现金物品和兼容的集成。
  • 可读的商店交易详情取决于集成插件是否传递结构化的交易信息。
  • 费用显示取决于交易是否包含费用元数据或通过结构化的 API 流程创建。
  • VaultUnlocked 支持取决于可用的 VaultUnlocked 环境和兼容的使用方式。
  • QuestLines 和 QuestLines Claims 支持是可选的，仅当这些集成存在并启用时才适用。
  • 其他插件可以通过此处文档化的公共 API 进行集成：https://api-yas-currency.web.app/

为什么选择 YASCurrency？

YASCurrency 专为需要比简单余额数字更多功能的 Hytale 服务器而构建。

它在一个原生的服务器经济系统中集成了基于账户的货币、实体现金支持、动态现金物品工具提示、玩家钱包 UI、可配置的余额 HUD、交易历史、QuestLines 支持、VaultUnlocked 支持、管理员工具、本地化、可选的 MariaDB 存储、存储诊断、迁移工具和公共集成 API。

通过经济控制更新，YASCurrency 还为服务器所有者提供了监控资金流动、审查交易来源、配置手续费和税收、检查玩家账户历史、通过冲正分录回滚可疑交易以及保护经济免受不受控制的货币创造的工具。

无论你是在构建一个简单的商店经济、一个角色扮演现金系统、一个玩家市场、一个任务驱动的 RPG 服务器、一个基于 Claim 的土地经济，还是一个自定义的服务器网络经济，YASCurrency 都能为你的服务器提供一个灵活而强大的基础。

近期变更

  • 添加了可选的 MariaDB 存储后端。
  • SQLite 仍然是默认的存储后端。
  • 添加了 SQLite 和 MariaDB 的存储后端抽象层。
  • 添加了 MariaDB 配置选项。
  • 添加了在 MariaDB 数据库已存在时自动创建表的功能。
  • 添加了存储诊断命令。
  • 添加了从 SQLite 到 MariaDB 的迁移命令。
  • 添加了迁移前创建 SQLite 备份的功能。
  • 添加了迁移后的账户数量、交易数量和总货币供应量的比较检查。
  • 改进了管理员存储健康性能，使用缓存的存储快照。
  • 改进了切换标签页时管理员 UI 的性能。
  • 改进了 MariaDB 设置错误消息。
  • 改进了活动存储后端的启动日志记录。
  • 添加了 MariaDB 设置和迁移文档。
  • 添加了重大经济控制更新。
  • 添加了交易监控仪表板。
  • 添加了用于审查资金流动的经济安全工具。
  • 添加了详细的管理员交易日志。
  • 添加了交易详情检查。
  • 添加了对选中条目的交易行高亮显示。
  • 添加了通过安全冲正交易实现回滚支持。
  • 添加了来源和外部 ID 封锁工具。
  • 在管理员账户标签页中添加了玩家账户详情视图。
  • 添加了带分页的玩家特定交易历史。
  • 添加了 QuestLines 奖励的可配置手续费。
  • 添加了 Claim 购买的可配置手续费。
  • 添加了 Claim 租金和续租的可配置手续费。
  • 添加了当元数据可用时在交易历史中显示手续费的支持。
  • 添加了可选的通胀控制设置。
  • 添加了可选的动态奖励缩放设置。
  • 添加了公共 API v4，包含 TransactionContext、FeePolicy、TransactionPreview 和 YasCurrencyTransactionResult。
  • 添加了上下文感知的存款、取款、转账、grantCash 和 spendCash API 流程。
  • 添加了针对 QuestLines 奖励和 Claim 付款的 API 辅助工具。
  • 改进了管理员本地化处理。
  • 改进了 VaultUnlocked 命名的一致性。
  • 改进了实体现金在钱包和 HUD 视图中的命名和显示处理。
  • 添加了使用 Hytale 物品堆叠显示元数据的动态现金物品名称和描述。
  • 添加了 QuestLines 对实体现金检查和现金消费的支持。
  • 添加了用于实体现金余额的 QuestLines 文本变量。
  • 改进了实体现金价值、现金标签和格式化现金余额输出的处理。
  • 改进了玩家钱包内的余额 HUD 设置。
  • 添加了余额 HUD 背景选择：标准、RPG 和 RPG 浅色。
  • 添加了余额 HUD 显示选项：数字余额、实体现金余额和货币图标。
  • 添加了每个玩家的 HUD 位置和偏移设置，支持实时预览。
  • 将 HUD 位置减少为稳定的角落位置：左上、右上、左下和右下。
  • 添加了可选的货币符号可见性设置。