Technical Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Frontend (React)                      │
├─────────────────────────────────────────────────────────────┤
│                     StarknetKit / Cartridge                   │
├─────────────────────────────────────────────────────────────┤
│                          Torii Indexer                        │
├─────────────────────────────────────────────────────────────┤
│                      Dojo Framework (ECS)                     │
├─────────────────────────────────────────────────────────────┤
│                    Cairo Smart Contracts                      │
├─────────────────────────────────────────────────────────────┤
│                         Starknet L2                           │
└─────────────────────────────────────────────────────────────┘

contracts/
├── systems/
│   ├── adventurer/     # Player character logic
│   ├── beast/          # Enemy AI and combat
│   ├── game/           # Core game loop
│   ├── loot/           # Item generation
│   ├── market/         # Trading system
│   └── settings/       # Configuration
├── models/
│   ├── adventurer/     # Character data structures
│   ├── beast.cairo     # Beast entities
│   ├── combat.cairo    # Combat state
│   ├── loot.cairo      # Item models
│   └── market.cairo    # Market state
└── libs/
    ├── game.cairo      # Game utilities
    └── settings.cairo  # Config helpers

client/src/
├── desktop/           # Desktop-optimized UI
│   ├── components/   # Reusable components
│   ├── overlays/     # Screen overlays
│   └── pages/        # Route pages
├── mobile/           # Mobile-optimized UI
│   ├── components/   # Mobile components
│   ├── containers/   # Screen containers
│   └── pages/        # Mobile routes
├── dojo/             # Blockchain integration
│   ├── useSystemCalls.ts    # Contract interactions
│   ├── useGameSettings.ts   # Settings hooks
│   └── useQuests.ts         # Quest system
├── stores/           # Zustand state management
│   ├── gameStore.ts # Game state
│   ├── marketStore.ts # Market state
│   └── uiStore.ts    # UI state
└── generated/        # Auto-generated bindings

struct Beast {
    id: u32,
    beast_type: BeastType,
    level: u8,
    health: u16,
    damage: u16,
    special_abilities: Array<Ability>,
}

struct Item {
    id: u32,
    item_type: ItemType,
    tier: Tier,
    level: u8,
    prefix: Option<Prefix>,
    suffix: Option<Suffix>,
    greatness: u8,
}

interface GameState {
  adventurer: Adventurer | null;
  currentBeast: Beast | null;
  market: MarketItem[];
  combatLog: CombatEvent[];
  isLoading: boolean;
}

// Efficient packing of multiple values
struct PackedStats {
    // All stats in single felt252
    packed: felt252,
}

// Multiple actions in single transaction
fn batch_actions(actions: Array<Action>) {
    // Process all actions together
}

const { connect, connectors } = useStarknet();
 
// Available connectors
const wallets = [argentX(), braavos(), cartridge()];

// Read operations (free)
const adventurer = await contract.get_adventurer(id);
 
// Write operations (gas required)
const tx = await contract.attack_beast();

#[event]
struct BeastSlain {
    adventurer_id: u256,
    beast_id: u32,
    gold_earned: u16,
    xp_earned: u32,
}

contract.on("BeastSlain", (event) => {
  updateGameState(event);
});

fn get_random_seed() -> felt252 {
    let info = get_block_info().unbox();
    pedersen(info.block_number, info.block_timestamp)
}

fn request_random() -> u256 {
    let vrf = IVRFProvider::new();
    vrf.request_random(callback)
}

fn validate_action(action: Action) {
    assert(action.is_valid(), 'Invalid action');
    assert(has_resources(), 'Insufficient resources');
}

mod ReentrancyGuard {
    fn start() {
        assert(!is_locked(), 'Reentrant call');
        set_locked(true);
    }
 
    fn end() {
        set_locked(false);
    }
}

const GamePage = lazy(() => import("./pages/GamePage"));
const MarketPage = lazy(() => import("./pages/MarketPage"));

// Zustand with persistence
const useGameStore = create(
  persist(
    (set) => ({
      // Minimal state updates
    }),
    { name: "game-storage" }
  )
);

// Use packed structs
// Minimize storage writes
// Batch operations

// Precompute values
// Use lookup tables
// Minimize loops

[environment]
rpc_url = "http://localhost:5050"
account_address = "0xDEV"
private_key = "0xDEV_KEY"

[environment]
rpc_url = "https://starknet-mainnet.public.blastapi.io"
account_address = "0xPROD"
private_key = "$PROD_KEY"

# Build contracts
sozo build
 
# Deploy to network
sozo deploy --world 0xWORLD_ADDRESS
 
# Verify deployment
sozo inspect

# Install dependencies
pnpm install
 
# Build for production
pnpm build
 
# Deploy to CDN
pnpm deploy

// Performance tracking
performance.mark("action-start");
await performAction();
performance.mark("action-end");
performance.measure("action", "action-start", "action-end");