Skip to content

TRADERS_README.md

Latest commit

 

History

History
319 lines (241 loc) · 10.2 KB

TRADERS_README.md

File metadata and controls

319 lines (241 loc) · 10.2 KB
Raw

🤝 Traders System — Implementation Status

Status: Phase 1 Complete ✅ | Architecture Ready for Phase 2
Date: April 4, 2026
Scope: Supply/Demand-driven autonomous NPC trader system

📦 What You Have Now

✅ Fully Implemented

  1. Database Schema (5 core tables)

    • File: sql/migrate_traders_system_v1.sql
    • Deploy: docker compose exec -T db mysql -uroot -proot galaxyquest < sql/migrate_traders_system_v1.sql

  2. REST API (6 endpoints)

    • File: api/traders.php
    • Status: All endpoints functional with full JSON responses
    • Ready to call from frontend or cron jobs

  3. Market Analysis Engine

    • File: api/market_analysis.php
    • Functions: Supply/demand calc, opportunity detection, dynamic pricing
    • Integration: Standalone, can be called independently

  4. Initialization Script

    • File: scripts/initialize_traders_system.php
    • Creates NPC traders per faction with realistic capital
    • Populates initial market opportunities
    • Run once: docker compose exec -T web php scripts/initialize_traders_system.php

  5. Documentation

    • TRADERS_SYSTEM_IMPLEMENTATION.md — Full architecture
    • TRADERS_INTEGRATION_GUIDE.md — API reference + testing
    • scripts/deploy_traders_system.sh — One-command deployment

🎯 Quick Validation Test

# 1. Deploy DB
docker compose exec -T db mysql -uroot -proot galaxyquest < sql/migrate_traders_system_v1.sql

# 2. Initialize traders
docker compose exec -T web php scripts/initialize_traders_system.php

# 3. List created traders
curl http://localhost/api/traders.php?action=list_traders | jq '.traders[].name'

# 4. See available opportunities
curl "http://localhost/api/traders.php?action=list_opportunities&min_margin=10" | jq '.opportunities[0]'

# 5. Check system supply/demand
curl "http://localhost/api/traders.php?action=market_analysis&system=1" | jq '.resources[]'

Expected output: JSON data showing traders, profitable routes, and system balances.

🔄 Architecture: How It Works

┌─────────────────────────────────────┐
│ 1. MARKET ANALYSIS                  │
│ (Calculate supply/demand per system)│
│ calculate_system_supply_demand()   │
└────────────┬────────────────────────┘
             │ Updates hourly
             ↓
    ┌──────────────────────────────┐
    │ market_supply_demand table   │
    │ (aggregated, persistent)     │
    └────────────┬─────────────────┘
                 │
                 ↓
    ┌──────────────────────────────────────┐
    │ 2. OPPORTUNITY DETECTION             │
    │ find_and_rank_opportunities()        │
    │ (Find arbitrage: A cheaper, B pricier)
    └────────────┬──────────────────────────┘
                 │ Ranked by profit %
                 ↓
    ┌──────────────────────────────────┐
    │ trade_opportunities table        │
    │ (1-hour validity window)         │
    └────────────┬─────────────────────┘
                 │
                 ↓
    ┌─────────────────────────────────────────────┐
    │ 3. TRADER DECISIONS (Next Phase)            │
    │ execute_trader_decisions()                  │
    │ (Allocate capital, create routes)           │
    └────────────┬────────────────────────────────┘
                 │ Creates active routes
                 ↓
    ┌──────────────────────────────────┐
    │ trader_routes table              │
    │ (planning → completed lifecycle) │
    └────────────┬─────────────────────┘
                 │
                 ↓
    ┌──────────────────────────────────┐
    │ 4. PRICE IMPACT (Next Phase)     │
    │ Update supply/demand on trades   │
    │ Cycle repeats                    │
    └──────────────────────────────────┘

💾 Database Tables

Table Records Purpose
npc_traders 10-30 NPC trader entities per faction
market_supply_demand ~60-100 Hourly aggregated supply/demand per system
trade_opportunities 50-200 Detected profitable routes (1h TTL)
trader_routes 0-50 Active in-flight trading missions
trader_transactions Audit log every buy/sell/transport action

📊 Key Endpoints

Get Traders

GET /api/traders.php?action=list_traders
→ Returns: All traders + capital + profit stats

Get Opportunities

GET /api/traders.php?action=list_opportunities&min_margin=15&limit=20
→ Returns: Profitable routes ranked by margin %

Get Market Analysis

GET /api/traders.php?action=market_analysis&system=1&galaxy=1
→ Returns: Supply/demand per resource in system

Process Tick

POST /api/traders.php?action=process_trader_tick
→ Runs: Trader lifecycle, opportunity updates (stub for Phase 2)

🚀 Next Steps (Priority Order)

Phase 2: Trader Lifecycle (3-5 days)

Goal: Make traders actually execute trades

  1. Implement process_route_transitions()

    • File: api/traders.php line ~300
    • States: planning → acquiring → in_transit → delivering → completed
    • Actions: buy goods, dispatch fleet, execute sale

  2. Implement execute_trader_decisions()

    • File: api/traders.php line ~320
    • Algorithm: Per trader, pick best opportunity, allocate capital, create route

  3. Fleet Integration

    • Link trader_routes ↔ fleets table
    • New fleet type: autonomous trader (no player control)
    • Buy/sell transactions tied to fleet delivery

Phase 3: Frontend Dashboard (2-3 days)

  1. Create Traders window (GQUI-based)
  2. Show live opportunities with profit projections
  3. Display trader performance leaderboard
  4. Market ticker with price changes
  5. Supply/demand graphs per system

Phase 4: Leader Integration (2-3 days)

  1. Trade Director leader role automation
  2. Passive income from trading network
  3. Auto-allocation of trader fleets
  4. Market price influence at high skill

🧪 How to Test

Automated Validation

# Check all components initialize correctly
php scripts/initialize_traders_system.php --reset

# Verify API responses
curl http://localhost/api/traders.php?action=list_traders
curl http://localhost/api/traders.php?action=list_opportunities

# Check data consistency
docker compose exec -T db mysql -uroot -proot galaxyquest \
  -e "SELECT COUNT(*) FROM npc_traders; SELECT COUNT(*) FROM trade_opportunities;"

Manual Testing

  1. Log into game
  2. Call /api/traders.php?action=market_analysis
  3. See which systems are buyers/sellers of what
  4. Check that opportunities are ranked by profit
  5. Verify traders exist and have capital

What To Expect

  • ✅ 10-30 traders created (depending on faction count)
  • ✅ 50-200 opportunities detected
  • ✅ Prices calculated dynamically
  • ✅ All API responses valid JSON
  • ✅ No database errors

📋 Key Configuration Points

Profitability Thresholds

File: api/market_analysis.php

// Minimum margin to consider a route viable
MIN_MARGIN_PCT = 15.0  // 15% profit

// Transport cost per light-year (estimated)
TRANSPORT_COST_PER_LY = 0.1  // 0.1 credits/LY

// Price elasticity (how much demand/supply affects price)
PRICE_ELASTICITY = 0.4  // Affects price sensitivity

Trader Behavior

File: scripts/initialize_traders_system.php

// Strategy distribution per faction
'helion' => 3 traders (profit_max)
'vor'    => 2 traders (volume)
'myrk'   => 2 traders (stabilize)

// Capital allocation per strategy
'helion'   => 75,000 Cr
'vor'      => 50,000 Cr
'myrk'     => 40,000 Cr

Market Update Frequency

Recommended: Run process_trader_tick every 10-15 minutes

# Via cron:
*/10 * * * * curl -s http://localhost/api/traders.php?action=process_trader_tick

🎓 Code Structure

api/
  ├── traders.php              ← API endpoints (fully done)
  └── market_analysis.php      ← Market analysis engine (fully done)

sql/
  └── migrate_traders_system_v1.sql  ← DB schema (ready to deploy)

scripts/
  ├── initialize_traders_system.php  ← One-time setup (ready)
  └── deploy_traders_system.sh       ← Quick deploy (shell)

docs/
  ├── TRADERS_SYSTEM_IMPLEMENTATION.md  ← Full architecture
  └── TRADERS_INTEGRATION_GUIDE.md      ← API reference

⚠️ Known Limitations (To Address in Phase 2)

  1. Traders don't actually trade yet — process_route_transitions() is a stub
  2. No fleet integration — Routes exist but aren't dispatched
  3. No price feedback loop — Market doesn't update after trades
  4. No player interaction — Players can't compete with traders (feature later)
  5. No UI — Everything API-driven currently

✨ Success Criteria (Phase 1 ✅)

  • ✅ Supply/demand correctly calculated per system
  • ✅ Profitable opportunities detected and ranked
  • ✅ Data persisted in database
  • ✅ API fully functional
  • ✅ Initialization script works end-to-end
  • ✅ Documentation complete
  • ✅ No warnings/errors in logs

📞 Questions?

See:

  • Full architecture: TRADERS_SYSTEM_IMPLEMENTATION.md
  • API docs: TRADERS_INTEGRATION_GUIDE.md
  • Quick start: scripts/deploy_traders_system.sh

Next session: Implement Phase 2 trader lifecycle → Watch traders execute real trades! 🚀