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

Shipping Box