FrameMarket v0.4.3

What is FrameMarket?

FrameMarket transforms ordinary Item Frames into fully functional marketplace shops that players can place and use directly in the world.

When players buy from a shop, the price rises. When players sell to a shop, the price falls. Over time, prices recover toward their configured base value, creating a self-regulating market that reacts to real server activity.

No sign walls. No complicated chest setup. No manual price babysitting. Players interact with a clean shop GUI, see the live price, understand the current trend, and trade instantly.

FrameMarket is built for survival, SMP, economy, towny and RPG servers that want a market that feels alive.

• Server: Spigot/Paper 1.21+
• Java: Java 21
• Required: Vault + a Vault-compatible economy plugin
• Required: MySQL
• Optional: PlaceholderAPI

Key Features

• Physical Item Frame Shops - Shops exist in the world. Players walk up to an Item Frame and trade through a GUI.
• Player-Owned Shops with Finite Stock - Players can create shops backed by real inventory items. If a shop has 40 Coal in stock, it can only sell 40 Coal until the owner restocks it.
• Admin Market Shops - Admins can create unlimited-stock global market shops with custom price limits and impact values.
• Live Supply and Demand Prices - Buys raise prices, sells lower prices, and every trade updates the shop immediately.
• Configurable Sell Spread - Players sell at a configurable percentage of the buy price, giving your economy a natural spread.
• Automatic Price Recovery - Prices slowly return toward base value over time, reducing long-term manipulation.
• Clean 3-Row Shop GUI - Buy and sell in quantities of 1, 8, 16, 32 or 64. The GUI shows wallet balance, stock, tax, live price and trend.
• 5-State Market Trend - HOT, RISING, STABLE, FALLING and CRASHING states help players understand market movement.
• Player-Owned Companies - Players can create and manage their own companies, attach their own shops, set tax/dividend rates, withdraw treasury money and transfer ownership.
• Admin/Server Companies - Admins can create fully configured server companies with custom share price, total shares, public shares, tax and dividend settings.
• Company Tax System - Attached shops collect company tax on trades. Tax goes into the company treasury and contributes to profit.
• Stock Market - Players can buy and sell shares in companies. Share prices update based on profit, volume and linked item trends.
• Dividends - Companies periodically distribute part of their profit to shareholders.
• Circuit Breakers - Stock trading can pause automatically after extreme price movement.
• Holograms - Vanilla TextDisplay holograms show item name, buy price, sell price and trend above shops.
• PlaceholderAPI Support - Use shop and market values in scoreboards, menus and other plugins.
• Anti-Abuse Protection - Cooldowns, wash-trade protection, daily limits, per-transaction caps and shareholder impact reduction.
• MySQL Storage - Shops, companies, stocks, transactions and limits are stored in MySQL.

How Shops Work

Creating a player shop with finite stock:

1. Place an Item Frame.
2. Put the item you want to sell inside the frame.
3. Keep matching items in your inventory.
4. Look at the frame and run /fm create <id> <price>.
5. All matching items in your inventory become the shop stock.
6. Use /fm restock later to add more stock.
7. Use /fm remove to close the shop and recover remaining stock.

Creating an admin unlimited-stock shop:

1. Place an Item Frame.
2. Put the item inside it.
3. Look at the frame and run /fm create <id> <price> as an admin.
4. The shop becomes a global market shop with unlimited stock.

Trading through the GUI:

• Clicking a shop frame opens the shop GUI.
• Players can buy or sell 1, 8, 16, 32 or 64 items.
• The GUI shows buy price, sell price, trend, balance and stock.
• Company shops show tax information before trading.
• Out-of-stock shops cannot sell more items.

Living Price System

FrameMarket uses absolute price impact per item:


Example:

• Base price: $100
• Buy impact: $2
• Player buys 5 items
• New price: $110

Sell price is based on a configurable multiplier:


Default multiplier is 0.80, meaning players receive 80% of the current buy price when selling.

Prices are clamped between each shop's minimum and maximum price. A recovery task slowly moves prices back toward base value, keeping markets active without letting old spikes last forever.


Market Trends

• HOT - Heavy buying activity
• RISING - More buys than sells
• STABLE - Balanced activity
• FALLING - More sells than buys
• CRASHING - Heavy selling pressure

Trend counters reset each recovery cycle, so the trend reflects recent activity instead of old history.




Player-Owned Companies

Players can now create their own companies and run a real business inside your server economy.

A company owner can:

• Create a company with /fm company create <id> <name>
• View owned companies with /fm company my
• Rename the company
• Set company tax within the configured limit
• Set dividend percent within the configured limit
• Add or remove materials from the company sector
• Attach their own shops to the company
• Detach shops from the company
• Withdraw money from the company treasury
• Transfer company ownership to another online player

Player companies are fully configurable:

• Enable or disable player-owned companies
• Creation cost
• Maximum companies per player
• Maximum shops per company
• Maximum player company tax
• Maximum player company dividend percent
• Default share price
• Default total shares
• Default public shares

Important ownership rule: regular players can only attach shops they own to companies they own. Admins can manage any company and any shop.




Companies, Stocks and Dividends

Companies are optional and controlled by stock-market.enabled.

How company tax works:

• A shop does not pay company tax by default.
• A shop must be explicitly attached to a company.
• When players trade in an attached shop, company tax is charged.
• Tax goes into the company treasury.
• Tax also counts as company profit for the current period.

How the stock market works:

• Players buy shares with /fm stock buy <companyId> <shares>.
• Players sell shares with /fm stock sell <companyId> <shares>.
• Share prices update each market cycle.
• Profit, volume and linked shop trends influence share movement.
• Maximum price movement per cycle is configurable.
• Circuit breakers can pause trading after extreme movement.

How dividends work:

• At the configured interval, companies distribute part of their period profit.
• Payments are proportional to shares held.
• The dividend pool is deducted from company treasury/profit.
• Online players receive a notification.

Commands

All commands use /framemarket or /fm.

Shop Commands

• /fm create <id> <price> - Create a shop from the targeted Item Frame.
• /fm create <id> <price> <min> <max> <buyImpact> <sellImpact> - Admin advanced shop creation.
• /fm remove - Remove the targeted shop. Owners can remove their own shops; admins can remove any shop.
• /fm restock - Add all matching inventory items into your shop stock.
• /fm info - View targeted shop details.
• /fm list - Admin list of all shops.
• /fm setprice <price> - Admin price reset.
• /fm setname <name> - Admin display name change.
• /fm setimpact <buyImpact> <sellImpact> - Admin impact change.
• /fm setlimits <minPrice> <maxPrice> - Admin price limit change.
• /fm reload - Reload config and messages.

Company Commands

• /fm company create <id> <name> - Create a player-owned company.
• /fm company my - View companies you own.
• /fm company list - View all companies.
• /fm company info <id> - View company details.
• /fm company rename <id> <name> - Rename an owned company.
• /fm company settax <id> <percent> - Set company trade tax within configured limits.
• /fm company setdividend <id> <percent> - Set dividend percent within configured limits.
• /fm company withdraw <id> <amount> - Withdraw money from company treasury.
• /fm company transfer <id> <player> - Transfer company ownership to an online player.
• /fm company additem <id> <MATERIAL> - Add a material to the company sector.
• /fm company removeitem <id> <MATERIAL> - Remove a material from the company sector.
• /fm company attachshop <companyId> <shopId> - Attach a shop to a company.
• /fm company detachshop <shopId> - Detach a shop from its company.
• /fm company delete <id> - Delete an owned company. Admins can delete any company.

Admin company creation:


This creates a server/admin company with full economic parameters.


Stock Commands

• /fm stock buy <companyId> <shares> - Buy shares at current share price.
• /fm stock sell <companyId> <shares> - Sell shares at current share price.
• /fm stock portfolio - View your holdings, value and unrealized PnL.

Example Company Flow

Player-owned company:


Admin/server company:





Permissions

• framemarket.admin - Access to all admin features. OP by default.
• framemarket.create - Allows players to create, remove and restock their own shops.
• framemarket.company.create - Allows players to create and manage player-owned companies.
• framemarket.shop.buy - Allows buying from shops.
• framemarket.shop.sell - Allows selling to shops.
• framemarket.stock.trade - Allows buying and selling company shares.
• framemarket.command.remove - Admin remove command.
• framemarket.command.list - Admin shop list command.
• framemarket.command.setprice - Admin price command.
• framemarket.command.setname - Admin name command.
• framemarket.command.setimpact - Admin impact command.
• framemarket.command.setlimits - Admin limits command.
• framemarket.command.reload - Admin reload command.
• framemarket.command.company - Admin company management.

Configuration Overview

Everything important is configurable in config.yml.

• MySQL host, port, database, username and password
• Default buy impact and sell impact
• Sell price multiplier
• Price recovery percent and task interval
• Stock market enable/disable
• Dividend interval
• Default company tax and dividend percent
• Maximum share price movement per cycle
• Circuit breaker percent and duration
• Player company enable/disable
• Player company creation cost
• Maximum companies per player
• Maximum shops per company
• Maximum player company tax
• Maximum player company dividend percent
• Default player company share settings
• Anti-abuse cooldowns, daily limits and transaction caps
• Frame protection
• Shop GUI mode
• Hologram lines and update interval
• All player-facing messages

Anti-Abuse Protection

• Transaction cooldown - Configurable delay between trades.
• Wash-trade protection - Prevents rapid buy/sell reversal on the same shop.
• Daily limits - Limits how much each player can buy or sell per shop per day.
• Per-transaction caps - Limits maximum buy/sell quantity per click.
• Shareholder impact reduction - Reduces price impact when shareholders trade their own company's goods.
• Finite stock enforcement - Player shops cannot sell more than their stored stock.
• Circuit breakers - Protect share trading from extreme movement.

Storage and Requirements

• Vault is required for economy integration.
• MySQL is required for persistent storage.
• PlaceholderAPI is optional for placeholders.

Important: FrameMarket requires MySQL. SQLite is not supported.




Recommended Server Types

• Survival servers - Let players build a real economy from in-world shops.
• SMP servers - Give players businesses, companies and investments.
• Towny/Nations servers - Use companies as town industries or player corporations.
• RPG servers - Create market-driven item values and trade routes.
• Economy servers - Add stocks, dividends, tax and treasury management.

Roadmap

Planned ideas for future versions. These are not required to use the current plugin.

Regional Markets

• Per-world independent prices
• WorldGuard region integration
• Market groups where shops influence each other
• Per-item volatility configuration

Analytics and Admin Tools

• Price history snapshots
• In-game price graph
• Most traded item leaderboard
• Price simulator
• Audit tools for suspicious trading

Quality of Life

• In-game visual editor
• More PlaceholderAPI values
• Expanded locale/multi-language support

Final Notes

FrameMarket is designed for server owners who want an economy with physical presence and real player behaviour behind it.

Players can run shops. Players can run companies. Investors can buy shares. Companies collect taxes, build treasury, pay dividends and react to trade activity.

The result is a Minecraft market that feels alive, understandable and configurable.