Shoppers - Lightman's Currency NPC Addon

Shoppers is a NeoForge 1.21.1 addon for Lightman's Currency that adds functional NPC customers to the game. These NPCs spawn around player-owned shops, browse inventory, buy products, use ATMs, and play casino slot machines, helping populate singleplayer worlds or servers with active economic participants.

---

Features

Spawn Behavior and Visuals

• Targeted Spawning: NPCs spawn within a 24-40 block radius of active player-owned shops and automatically pathfind toward commercial hubs.
• Biome-Specific Skins: Shoppers render with layered biome clothing (Plains, Taiga, Desert, and Snow) seamlessly composed over base villager models.
• Custom Names: Over 50 economy-themed names (such as Scrooge McDirt, Stonks Steve, and WallStreet Wally) display in 3D above customer heads.
• Vanilla Speeds: Shoppers walk at realistic speeds (matching standard vanilla villagers) rather than running erratically.

---

Economic Classes

Customers belong to one of four classes, which determines their starting currency and item interests:

1. Peasants: Hold iron coins. Buy basic building blocks (dirt, cobblestone, oak wood, seeds, and cheap food).
2. Citizens: Hold gold coins. Buy everyday items (coal, wool, torches, beds, cooked food, and glass).
3. Merchants: Hold emerald coins. Buy tools, weapons, armor, raw/cooked ores, ingots, and shields.
4. Tycoons: Hold netherite coins. Buy high-value items (diamonds, enchanted books, shulker boxes, totems, and elytra).

---

Smart AI Interactions

• Universal Shop Compatibility: Shoppers interact with all Lightman's Currency trade blocks, including vending machines, shelves, freezers, fridges, display cases, armor stands, bookshelf traders, card displays, and auction stands.
• Virtual Wallets and Automatic Exchange: Shoppers carry unified copper-equivalent budgets. They can buy low-value items using high-tier coins, and the mod handles coin deduction and returns change automatically.
• Crowd Prevention: Shoppers check if a trade block, ATM, or casino machine is occupied by another entity within 1.5 blocks. If occupied, they will bypass it to prevent piling up.
• ATM Pathfinding: When a shopper's wallet drops below 500 copper coins, they pathfind to nearby ATMs to withdraw or deposit funds, choosing random unoccupied ATMs to distribute crowds.

---

Realistic Gambling Mechanics

Shoppers evaluate slot and gacha machine risks before playing:

• Odds Checking: Shoppers inspect the weighted rewards and total weights of slot machines using safe reflection.
• Risk Thresholds: Citizens and Peasants refuse to play machines with a win chance below 15%. Tycoons and Merchants accept riskier machines down to 5%.
• Reckless Behavior: There is a 10% chance an NPC ignores the odds completely and plays anyway.

---

Daily Schedule

The marketplace follows a daily cycle based on game time:

• Morning Rush Hour (Ticks 1000 - 4000): Shoppers spawn twice as fast, local hub capacity increases by 50%, and shoppers walk at a slightly faster pace (0.75 modifier).
• Evening Casino Rush (Ticks 9000 - 12000): Casino crowds peak. Tycoons and citizens emerge to play slot machines and bid on auction stands.
• Night Closing (Ticks 13000 - 23000): Spawning is almost entirely halted. Shoppers move slowly (0.45 modifier) and will despawn with a puff particle effect if they are far from active players.

---

Crafting Valuation Engine

• Dynamic Worth Calculator: Custom or modded items without predefined prices are valued dynamically by recursively checking the server's recipe registry, summing ingredient values, and dividing by the output count.
• Custom Values: Server operators can define custom item values using /shoppers value set <item> <copper_worth>.
• Bargain Hunters: Shoppers prioritize deals with high bargain scores (market value vs. price ratio). If they spot a deal discounted by 40% or more, they will buy it even if the item falls outside their class interests.

---

Performance and Optimization

• SavedData Registry: Coordinate data for all placed economic blocks is stored globally in ShoppersWorldData, completely removing the need for heavy tick-based block scanning in AI goals.
• Player-Centric Scanning: An optimized background loop scans chunks near active players every 5 seconds to automatically discover and register pre-existing shops.
• AI Pathfinding Cooling: AI goals apply strict cooldowns if a target block becomes unreachable, eliminating pathfinding spam and tick spikes.

---

Commands

• /shoppers value <item> - Returns the calculated market worth of an item.
• /shoppers value set <item> <copper_worth> - Configures a persistent custom value for an item (requires administrator permissions).

---

Requirements and Compatibility

• Lightman's Currency (Required)
• NeoForge 1.21.1
• Out-of-the-box compatibility with modded items and sub-addons.