Progress Report

May 5 2025

Project Documentation for Bull Run Boost: Shadow Markets

1. Project Layout

The project is structured around a dual gameplay loop (daytime ranching in Cipher Gulch and nighttime black market in the Ether Range), with a focus on financial literacy, cypherpunk themes, and MPL-404 tokenomics. Here’s the high-level layout:

• Core Modules:

  • Main Menu: Character selection (Entrepreneur, Adventurer for MVP), basic UI.

  • Daytime (Cipher Gulch): Ranch management scene, Saloon for wagers, community events.

  • Nighttime (Ether Range): Black market scene with crafting, trading, and heist missions.

  • Tokenomics: $CATTLE and MPL-404 asset management (mock for MVP, Solana integration later).

  • Educational Layer: Tooltips and quests to teach budgeting, risk management, and market dynamics.

• Assets:

  • 2.5D pixel art for Cipher Gulch (Western plains, barns, Saloon) and Ether Range (dark forests, neon markets).

  • Character sprites for Entrepreneur (cowboy hat, suit) and Adventurer (cowboy hat, leather jacket).

  • UI elements: Resource stats, inventory lists, buttons.

• Technical Stack:

  • Unity (2D project, C# scripts) for the MVP.

  • JavaScript prototypes on Replit (for reference, covering farming, harvesting, Saloon games).

  • Solana integration (mocked for MVP, full integration later).

2. Iterations and Changes

Here’s a summary of the project’s evolution based on your progress:

• Initial Concept: Started as a Web3 card game (Horse Race adaptation) to teach investing, with meme coins/NFTs as "horses."

• Pivot to BRB: Expanded into a cypherpunk Western game with dual gameplay—ranching by day, black market by night.

• JavaScript Prototypes: Built non-animated apps on Replit to simulate farming, harvesting, user rewards, Saloon card games, gambling, and odds management.

• Market Research: Identified a $732 million SAM and 3,000 potential DAU, focusing on 17–mid-40s audience.

• User Flows and Journeys: Created detailed flows for day-night cycles and character archetypes (Entrepreneur, Adventurer, etc.), with emotional arcs.

• Wireframing: Designed wireframes for main menu, ranch, Saloon, and Ether Range scenes.

• Asset Generation: Began creating pixel art assets for Cipher Gulch and Ether Range.

• Unity Transition: Now moving to Unity for an animated 2.5D MVP, adapting JavaScript functionality.

3. Checklists

These checklists will help you track tasks and ensure nothing is missed during development.

General Development Checklist:

• Define project scope and MVP requirements.

• Document user flows and character journeys.

• Conduct market research and user interviews.

• Build JavaScript prototypes for core mechanics.

• Set up Unity project with 2D configuration.

• Create main menu scene with character selection.

• Implement Daytime Ranch scene (resource management, cattle breeding).

• Implement Saloon scene (Cipher Poker, $CATTLE wagers).

• Implement Nighttime Ether Range scene (crafting, trading).

• Add basic animations (character idle, UI hover/click).

• Test MVP for functionality and player feedback.

• Integrate educational tooltips (budgeting, risk management).

MVP Testing Checklist:

• Verify character selection saves and loads stats.

• Test resource management (Hay, Water) for accuracy.

• Ensure $CATTLE wagers in Saloon burn 10% correctly.

• Confirm crafting in Ether Range deducts $CATTLE (50% burn).

• Check scene transitions (day-night cycle, fade effects).

• Validate UI updates (inventory, resource stats).

• Collect player feedback on gameplay and learning.

---

4. Functions and Explanation of the Project

Here’s a list of key functions and their explanations, reflecting the project’s current state and goals.

• Character Selection:

  • Function: Allows players to choose between Entrepreneur (+10% $CATTLE earnings) or Adventurer (+10% heist success).

  • Explanation: Sets up player stats and archetype bonuses, impacting gameplay (e.g., Entrepreneur earns more from ranch sales, Adventurer excels in Ether Range missions).

• Resource Management (Daytime):

  • Function: Players allocate Hay and Water to breed MPL-404 cattle and sustain the ranch.

  • Explanation: Teaches budgeting by balancing resources; running out halts progress (e.g., can’t breed cattle without 10 Hay/Water).

• MPL-404 Cattle Breeding:

  • Function: Consumes resources to mint mock MPL-404 NFTs with traits (Speed, Milk Production).

  • Explanation: Simulates blockchain asset creation, teaching asset management; traits affect $CATTLE earnings (e.g., higher Milk Production yields more).

• Facility Upgrades:

  • Function: Spend $CATTLE to increase Hay/Water capacity or improve cattle stats.

  • Explanation: Introduces investment concepts; upgrades scale the ranch but require financial planning.

• Saloon Wagers (Cipher Poker):

  • Function: Players wager $CATTLE (10% burn) in a 50/50 poker game.

  • Explanation: Teaches risk management; burning tokens controls $CATTLE supply, reflecting real-world tokenomics.

• Crafting in Ether Range:

  • Function: Craft Shadow Potions using $CATTLE (50% burn), adding them as MPL-404 NFTs to inventory.

  • Explanation: Introduces advanced economics; burns simulate market friction, and crafting teaches resource allocation.

• Trading in Ether Range:

  • Function: Sell Shadow Potions for $CATTLE, with prices varying based on mock supply/demand.

  • Explanation: Teaches market dynamics; players learn to adjust to fluctuating prices (e.g., 25–35 $CATTLE per potion).

• Cross-World Intelligence:

  • Function: Use Saloon gossip to inform Ether Range trades, or Ether Range intel to avoid ranch audits.

  • Explanation: Encourages strategic thinking across both worlds, tying the dual gameplay together.

• Educational Tooltips:

  • Function: Display tips during gameplay (e.g., “Budgeting: Balance Hay and Water to avoid shortages”).

  • Explanation: Ensures players learn financial literacy and economics without breaking immersion.

---

5. Must-Haves, Wants, and Not Needed

This section categorizes features based on priority for the MVP and overall game vision.

• Must-Haves (Essential for MVP and Core Experience):

  • Character selection (Entrepreneur, Adventurer) with basic stats.

  • Daytime Ranch scene: Resource management (Hay, Water), MPL-404 cattle breeding, barn upgrades.

  • Saloon scene: Cipher Poker with $CATTLE wagers (10% burn, 50/50 odds).

  • Nighttime Ether Range scene: Craft Shadow Potions (50% $CATTLE burn), sell potions with variable pricing.

  • Basic UI: Resource stats, inventory, $CATTLE balance.

  • 2.5D pixel art visuals for Cipher Gulch and Ether Range (using free assets).

  • Day-night cycle UI indicator (e.g., sun/moon icon).

  • Scene transitions with fade effects.

• Wants (Enhancements for Post-MVP):

  • Full Solana blockchain integration for $CATTLE and MPL-404 transactions.

  • Additional archetypes (Scientist, Outlaw, Guardian) with unique stats.

  • Heist missions in Ether Range (steal resources, avoid Ether Guards).

  • Community events in Cipher Gulch (ranch tours, crafting fairs).

  • Social features: Saloon chat, black market bazaars.

  • Advanced animations: Character walking, cattle movement, potion crafting effects.

  • Dynamic supply/demand system in Ether Range (e.g., dragon-slaying events affect prices).

  • Reputation systems (Cipher Gulch public reputation, Ether Range underground reputation).

• Not Needed (Out of Scope or Low Priority):

  • Full 3D graphics (game stays 2.5D for style and simplicity).

  • Real-time multiplayer (MVP focuses on single-player with simulated NPCs).

  • Complex AI for NPCs (basic interactions suffice for MVP).

  • Extensive lore library (MPL-404 Story Cards can be added later).

  • Mobile app version (focus on desktop/web for now).

---

6. MVP Requirements vs. Future Functions

This section separates what the MVP must include from features that can be added later.

• MVP Requirements (What It Definitely Needs):

  • Character Selection: Choose between Entrepreneur and Adventurer, with stats affecting gameplay (e.g., $CATTLE earnings, heist success).

  • Daytime Ranching:

    • Manage Hay and Water (start with 100 each).

    • Breed MPL-404 cattle (consume 10 Hay/Water, mock NFT with traits).

    • Upgrade barn (cost 50 $CATTLE, increase resource capacity by 50).

  • Saloon Wagers:

    • Cipher Poker: Wager 1–50 $CATTLE, 10% burn, 50/50 win/loss.

    • Display outcome (e.g., “Won 36 $CATTLE!”).

  • Nighttime Black Market:

    • Craft Shadow Potion (cost 20 $CATTLE, 50% burn, mock MPL-404 NFT).

    • Sell potion for 25–35 $CATTLE (randomized price).

  • Visuals and UI:

    • 2.5D pixel art for ranch, Saloon, and Ether Range (free assets).

    • UI for resources, inventory, and $CATTLE balance.

    • Day-night cycle indicator and fade transitions.

  • Educational Elements:

    • Basic tooltips (e.g., “Budgeting: Don’t overspend resources!”).

• Functions to Add Later (Post-MVP Enhancements):

  • Blockchain Integration: Full Solana support for $CATTLE transactions, MPL-404 minting, and secondary market trading (30-day vesting).

  • Expanded Gameplay:

    • Heist missions in Ether Range (steal Dragon Scales, avoid guards).

    • Community events in Cipher Gulch (earn reputation, $CATTLE).

    • Dynamic market events (e.g., dragon-slaying increases potion demand).

  • Social Features:

    • Saloon hangouts (chat, form alliances).

    • Black market bazaars (trade with simulated players).

  • Reputation Systems:

    • Cipher Gulch public reputation (affects trade deals, audit risk).

    • Ether Range underground reputation (affects buyers, detection risk).

  • Educational Depth:

    • Quests teaching advanced economics (e.g., “Analyze supply/demand”).

    • NPC dialogues on cypherpunk themes (e.g., decentralization).

  • Polish:

    • Advanced animations (walking, crafting effects).

    • Sound effects (e.g., cattle mooing, poker chip sounds).

    • Additional archetypes and character customization (skins).

---