5.2 KiB
CLAUDE.md — Project Instructions
Project Name
DopeWars-2025
Project Intent
Build a modern, real-world, asynchronous market & logistics simulation inspired by classic Dope Wars.
This is a strategy game about time, geography, pressure, and consequence.
This is NOT:
- A turn-based game
- A real-time PvP game
- A live flight booking app
- A trading simulator with charts everywhere
Non-Negotiable Constraints
- $0 budget
- No paid APIs
- No scraping airline or travel websites
- No live flight booking
- All realism must be simulated using open/static data
- iPad-friendly development (browser / VS Code Web)
- Systems must work offline where possible
Core Design Pillars (Never Break These)
-
Time Is Real
- The world runs continuously
- Markets move whether the player is active or not
- Travel takes real time
-
Commitment Has Consequences
- When travel is booked, trading is locked until arrival
- Missed opportunities are intentional, not accidental
-
The World Reacts, It Never Explains
- Multiplayer effects are discovered slowly
- No UI labels for “other players”
- No explicit explanations of cause
Starting Conditions (LOCKED DEFAULTS)
- Starting Cash: $20,000
- Starting Debt: $30,000
- Inventory Capacity: 100 units
- Debt Interest: ~0.8% per real-world hour (compounding)
- Debt exists immediately at game start
The player begins already under pressure.
Debt & Loan Shark Rules
- The player starts with mandatory debt
- Debt accrues interest in real time, even while offline
- Debt can ONLY be paid, reduced, or renegotiated in the city of origin
- The loan shark is permanently tied to the starting city
- Ignoring debt causes gradual escalation:
- Higher interest
- Increased enforcement pressure
- Reduced effectiveness of bribes, fixers, and safehouses
- Failure is gradual escalation, not instant loss
Debt creates a gravitational pull back to the origin city.
Travel System Rules
- Travel uses static/open data only (airports, distance, heuristics)
- Flight duration is calculated, not looked up live
- No fast travel
- No skipping time
Travel Classes:
- Economy: cheapest, slowest, highest scrutiny
- Business: balanced, reduced risk
- First: expensive, fastest, lowest scrutiny, limited special actions
Once travel begins:
- Trading is disabled
- Prices continue to update
- Market visuals continue to animate
Market & Pricing Rules
- Prices are explicit and numeric
- Prices are lowest near manufacturing regions
- Prices rise with:
- Distance from source
- Enforcement pressure
- Scarcity
- Aggregate player activity
Prices may spike or crash dramatically.
Market Visualization Rules
UI must show:
- Current price (always visible)
- Percent change (simple ▲ / ▼)
- A visual market signal (e.g. volatility ribbon / pulse)
UI must NOT show:
- Candlestick charts
- OHLC data
- Exact historical tables
- Technical indicators (RSI, MACD, etc.)
Visuals should convey:
- Momentum
- Volatility
- Liquidity
- Instability
The goal is intuition, not analysis paralysis.
Inventory Rules
Inventory is physical:
- Volume limits apply
- Bulk increases risk and friction
- Optional decay/spoilage over time
- Storage limits vary by city
- Safehouses reduce loss and exposure
No infinite hoarding.
Law Enforcement Model
- ~180 countries
- One national enforcement org per country (fictionalized names)
- Attributes include:
- Aggression
- Reach
- Efficiency
- Corruption
- International cooperation
Heat is:
- Country-specific
- Transferable across borders
- Influenced by volume, time exposed, and transport method
Players never fight law enforcement directly. Pressure is environmental.
Multiplayer Philosophy (CRITICAL)
- Multiplayer is asynchronous and indirect
- Players never see:
- Other players
- Player names
- Player locations
- Player inventories
Players influence the world only through:
- Aggregate demand
- Market volatility
- Enforcement pressure
Discovery of multiplayer effects must be gradual and implicit.
The world never says “another player did this”.
Code Organization Rules
- Backend logic must be deterministic
- UI must not contain business logic
- Each system lives in its own file
- Avoid monolithic “god files”
Preferred structure:
- backend/ → world logic
- frontend/ → UI only
- data/ → static datasets
- docs/ → rules and explanations
AI Agent Expectations
When coding:
- Prefer clarity over cleverness
- Explain why in comments, not what
- Never introduce paid services
- Never assume real-time multiplayer visibility
- Ask before adding complexity
When uncertain:
- Default to simpler mechanics that preserve tension
- Preserve consequences over convenience
Design North Star
If a feature:
- Reduces planning
- Removes commitment
- Eliminates risk
- Explains the system too clearly
…it probably does not belong.
- Player may start in any city with an international airport
- Starting city permanently anchors the loan shark and debt mechanics
The game should feel like:
“The world keeps moving, and I’m already behind.”