CeraEconomy

# CeraEconomy — Overview

CeraEconomy is a lightweight and configurable economy plugin for Paper Minecraft, designed to provide a complete server economy system with player balances, payments, banking, leaderboards, shops, selling, persistent storage, and legacy data migration.

## Core Systems

### Economy
- Player balance management.
- `/balance` and `/bal` to view balances.
- `/pay` for player-to-player payments.
- `/eco` for economy administration.
- Supports setting, adding, removing, and transferring money.
- Uses BigDecimal for accurate monetary values.
- Persistent economy storage.
- Autosave support.
- Transaction management.

### Bank
- Separate bank balance system.
- Deposit and withdrawal support.
- Bank balance management.
- Bank GUI.

Commands:
- `/bank balance`
- `/bank deposit`
- `/bank withdraw`

### Balance Top

Commands:
- `/baltop`
- `/balancetop`
- `/topbalance`

Displays players with the highest economy balances.

## Shop System

The Shop system provides a configurable GUI-based marketplace where players can browse sections, view shops, purchase configured items, and pay directly using their economy balance.

Player commands:
- `/shop`
- `/ceshop`
- `/cshop`

Features:
- Main shop GUI.
- Shop sections.
- Individual shop GUIs.
- Configurable item slots.
- Configurable item prices.
- Automatic economy payments.
- Direct item delivery.
- Balance checks.
- Inventory space protection.
- Clickable GUIs.

### Shop Management

Admins can create and manage shops and shop items.

Commands:
- `/shop add <shop> <slot>`
- `/shop set <shop> <slot>`
- `/shop set <shop> <name>`
- `/shop <shop> add <item> <price> <slot>`
- `/shop <shop> set <item> <price>`
- `/shop <shop> reset`

The `reset` command only clears the shop's `Items` section. It does not delete the shop, section, slot, name, title, or display settings.

## Shop & Section Architecture

Shop data is separated into `Shops/` and `Sections/`.

Example:

Shops/
└── Food.yml

Sections/
└── Food.yml

Shop and Section files use the same filename to remain linked.

Automatic features:
- Creates missing shop files.
- Creates missing section files.
- Automatically finds available section slots.
- Synchronizes Shops and Sections.
- Provides `Example.yml` templates.

## Shop GUI

The Shop GUI can be configured through `config.yml`.

Supported GUI sizes:
- 9
- 18
- 27
- 36
- 45
- 54

Default configuration:

shop:
Enabled: true
Size: 54
Fill:
Enabled: true
Block: BLACK_STAINED_GLASS_PANE

## Sell System

The Sell system allows players to sell configured items through the economy system.

Player commands:
- `/sell`
- `/cesell`
- `/csell`

Admin commands:
- `/sell add <item> <price>`
- `/sell set <item> <price>`
- `/sell remove <item>`

Includes item and price validation.

## Data & Storage

CeraEconomy uses persistent data storage to keep player economy information between server restarts.

The plugin also uses versioned data folders to keep data separated between plugin versions.

Example:

CeraEconomy-1.4.5/
├── config.yml
├── Shops/
├── Sections/
└── ...

## Legacy Data Import

CeraEconomy includes a Legacy Data Import system for migrating data from older CeraEconomy versions.

The importer:
- Detects older `CeraEconomy-x.x.x` folders.
- Selects the newest valid legacy version.
- Automatically determines supported legacy storage formats.
- Imports compatible economy data.
- Logs the import source and version.
- Reports imported accounts and skipped data.
- Safely handles missing or invalid legacy data.
- Automatically disables the import option after completion.

Supported legacy storage:

- `< 1.3.0` → YAML
- `1.3.0 - 1.3.3` → YAML + MySQL
- `> 1.3.3` → YAML + MySQL + SQLite

Import can be enabled through:

import-data: true

The option defaults to `false` and is automatically reset to `false` after the import process.

## Compatibility

- Paper API 1.21
- Vault — soft dependency
- PlaceholderAPI — soft dependency

## Architecture

CeraEconomy is organized around several independent systems:

CeraEconomy
│
├── Economy
│ ├── Balance
│ ├── Payments
│ ├── Administration
│ └── Storage
│
├── Bank
│ ├── Deposit
│ ├── Withdrawal
│ └── Bank GUI
│
├── Shop
│ ├── Sections
│ ├── Shops
│ ├── Shop Items
│ ├── Shop GUI
│ └── Purchasing
│
├── Sell
│ ├── Sell GUI
│ └── Sell Configuration
│
├── Balance Top
│
└── Legacy Data Import

## Version History

### CeraEconomy 1.4.6
- Added Legacy Data Import.
- Added automatic legacy version detection.
- Added YAML, MySQL, and SQLite legacy import support.
- Added safer migration handling.
- Added detailed import logging.
- Updated plugin version to 1.4.6.

### CeraEconomy 1.4.5
- Expanded the Shop system.
- Added shop item management.
- Added shop purchasing.
- Integrated Shop with the Economy system.
- Added `/shop <shop>`.
- Added item reset functionality.
- Added clickable shop and item GUIs.
- Added balance and inventory checks.
- Updated the default shop fill material.

### CeraEconomy 1.4.4
- Introduced the Shop system.
- Added `/shop`, `/ceshop`, and `/cshop`.
- Added configurable Shop GUI sizes.
- Added configurable GUI fill.
- Added Shops and Sections folders.
- Added Shop Section synchronization.
- Added automatic free-slot detection.
- Added `/cesell` and `/csell`.

### CeraEconomy 1.4.3
- Previous stable foundation before the Shop system.

## Summary

CeraEconomy is an all-in-one economy solution for Paper servers.

It combines:

Economy + Bank + Balance Top + Shop + Sell + Persistent Storage + Legacy Migration

The plugin is designed to provide a simple but extensible economy experience for both players and administrators, while keeping shop data, economy data, and version-specific data organized and manageable.

MIT License