English

I. Core Mechanics

• Exchange Logic

  • Define "exchange rules" through data packs
  • After placing items in the shipping box, exchange will occur at 6:00 the next day according to the rules set in the "exchange rules"

• Output Dynamic Threshold Mode

  • Type: dynamic_pricing
  • Threshold array threshold: Defines sales volume critical points for price changes (e.g., [100, 500, 1000])
  • Value array value: Corresponding output quantities after each threshold (e.g., [5, 3, 1])
  • Reset time day: Number of days until threshold reset
  • day = -1: Sales count never resets, accumulates indefinitely
  • day = 0: Sales count automatically resets to 0 daily
  • day = N (N > 0): Sales count resets every N days
  • Correspondence: Threshold array and value array must correspond one-to-one
  • Price Calculation Rules:
  • Sales volume < minimum threshold → Use first tier price
  • Sales volume ≥ maximum threshold → Use last tier price
  • Sales volume between thresholds → Use corresponding tier price
  • Statistics Scope: Sales statistics shared among all players
  • Can be configured per item in JSON whether to enable

• Output Weight Mode

  • In this mode, item output randomly obtains an item based on weight

II. User Interface & Interaction

• JEI Integration
  • Items automatically have exchange information, supporting JEI list display of item exchange information
• Configuration Error Alerts
  • In-game alerts when "exchange rules" are configured incorrectly

III. Configuration Method

• Rule File Path
  • "Exchange rules" must be placed in the data/shipping_box/exchange_rules/ folder
• File Format
  • Files must be JSON, multiple JSON files are supported
• Input/Output Configuration
  • Supports any item as input/output, with customizable quantities
  • Supports input/output data components, input components support NBT ranges, output items support weight and dynamic thresholds
  • Components have two formats: String format and JSON object format, JSON object format is recommended

Item Attribute System

Selling Price Boost Attribute

• Attribute Name: selling_price:selling_price_boost
• Default Value: 0.0
• Maximum Value: 10.0
• Function Description: This attribute affects item selling price as a percentage, higher values yield more when selling
  • For example: selling_price_boost = 0.5 means a 50% price increase
  • selling_price_boost = 2.0 means a 200% price increase
• Application Scope: Applies to all exchangeable items, including:
  • Item-to-item exchange mode
  • Virtual currency exchange mode
• Configuration Method: Currently unobtainable in normal game modes

IV. Integrated Mod

ViScriptShop

• Crawler Coin
  • Right-click Crawler Coin to exchange for virtual currency based on the currency price displayed in the item tooltip
  • Sneak + Right-click to exchange one full stack
• Secondary Coin Pouch
  • Hold "Secondary Coin Pouch" and right-click to convert physical currency or check balance
  • Sneak + Right-click to exchange physical currency from containers
• Exchange Rule Extensions
  • In "exchange rules", if item in output is replaced with "coin": true, the input item will be directly exchanged for the mod's virtual currency, supporting dynamic thresholds

Ecliptic Seasons

Season-Based Pricing Mechanism

• Function Description: Determines whether items being sold match the current season and adjusts their prices accordingly based on seasonal status
• Compatibility Note: This mode is not compatible with ViScriptShop's virtual currency (VSS) mode
• Core Mechanics:
  • In-season items: Receive price bonuses
  • Off-season items: Suffer price reductions
  • Configurable option to restrict sales to specific seasons only

Seasonal Configuration Guide

• season Field: Must use array format, allowing multiple seasons to be set simultaneously
  • Example: ["spring", "autumn"] indicates both spring and autumn seasons
• seasonal_only Function:
  • true: Items can only be sold during specified seasons; unavailable for exchange in other seasons
  • false: Items can be sold year-round, but prices fluctuate based on the season
• Price Calculation Formula:
  • In-season: Final Price = Base Price × (1 + add_season_bonus/100)
  • Off-season: Final Price = Base Price × (1 - reduce_season_bonus/100)

For more JSON details, please refer to the README file on GitHub.

https://github.com/WitherRedstone/Shipping-Box/blob/master/README.md

=====================================================================

中文

一、核心机制

• 兑换逻辑
  • 通过数据包定义"兑换规则"
  • 将物品放入售货箱后，在第二天6:00会按照"兑换规则"内设置的规则进行兑换
• 输出动态阈值模式
  • 类型：dynamic_pricing（动态定价）
  • 阈值数组 threshold：定义价格变更的销量临界点（如 [100, 500, 1000]）
  • 价值数组 value：对应每个阈值后的输出数量（如 [5, 3, 1]）
  • 重置时间 day：阈值重置所需天数
  • day = -1：销售计数永不重置，会一直累加
  • day = 0：每天自动重置销售计数为0
  • day = N（N > 0）：每N天重置一次销售计数
  • 对应关系：阈值数组和价值数组必须一一对应
  • 价格计算规则：
  • 销量 < 最小阈值 → 使用第一档价格
  • 销量 ≥ 最大阈值 → 使用最后一档价格
  • 销量介于阈值之间 → 使用对应档位价格
  • 统计范围：所有玩家共享销售统计
  • 可在JSON中为每个物品配置是否启用
• 输出权重模式
  • 在这个模式下，物品输出会根据权重来随机获得一个物品

二、用户界面与交互

• JEI集成
  • 物品自动有兑换信息，支持jei列表显示物品的兑换信息
• 配置错误提醒
  • "兑换规则"配置错误时会在游戏内提醒

三、配置方式

• 规则文件路径
  • 需要将“兑换规则”放入到data/shipping_box/exchange_rules/文件夹内
• 文件格式
  • 文件必须是json，可以有多个json
• 输入/输出配置
  • 支持任意物品作为输入/输出，且数量可自定义
  • 支持输入/输出数据组件，输入组件支持nbt区间，输出物品支持权重、动态阈值
  • 组件有两种格式，字符串格式和JSON对象格式，推荐用JSON对象格式

物品属性系统

售价加成属性

• 属性名称：selling_price:selling_price_boost
• 默认值：0.0
• 最大值：10.0
• 功能说明：该属性以百分比形式影响物品售价，数值越高，出售所得越多
  • 例如：selling_price_boost = 0.5 表示售价提升 50%
  • selling_price_boost = 2.0 表示售价提升 200%
• 应用范围：适用于所有可兑换物品，包括：
  • 物品兑换物品模式
  • 虚拟货币兑换模式
• 配置方式：暂时无法在常规模式下获得

四、联动模组

ViScriptShop

• 爬爬币
  • 右键爬爬币会根据物品提示显示的货币价格兑换虚拟货币
  • 潜行右键换取一组
• 次元钱袋
  • 手持"次元钱袋"右键转换实体货币或查询余额
  • 潜行右键兑换容器内的实体货币
• 兑换规则扩展
  • 在“兑换规则”中，若将 output 中的 item 替换为 "coin": true，则输入物品将被直接兑换为模组的虚拟货币，支持动态阈值

节气

季节影响系统

• 功能说明：判断售卖的物品是否在当前季节，根据季节状态调整售价
• 兼容性说明：此模式不兼容ViScriptShop的虚拟货币（VSS）模式
• 核心机制：
  • 应季物品：获得售价加成
  • 非应季物品：受到售价减益
  • 可配置是否仅允许在特定季节出售

季节配置说明

• season字段：必须使用数组格式，可同时设置多个季节
  • 例如：["spring", "autumn"] 表示春季和秋季
• seasonal_only功能：
  • true：物品只在设定的季节可以出售，其他季节无法兑换
  • false：物品全年可出售，但价格会根据季节浮动
• 价格计算公式：
  • 应季时：最终售价 = 基础价格 × (1 + add_season_bonus/100)
  • 非应季时：最终售价 = 基础价格 × (1 - reduce_season_bonus/100)

更多JSON详情，请参阅 GitHub 上的 README 文件。

https://github.com/WitherRedstone/Shipping-Box/blob/master/README.md