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.