How it works

CAIVEMEN combines AI decision-making, blockchain data, and real-time simulation into a primitive survival game where market activity directly influences the world.

The Basic Loop

1

Solana Transaction

2

Helius gRPC Stream (real-time)

3

Transaction Classification (buy/sell/transfer, size)

4

World Effect (food spawn, disaster, tension increase)

5

AI Decision Loop (every 3 seconds)

6

Caveman Actions (move, attack, flee, eat)

7

State Update + Firestore Log

8

WebSocket Broadcast (200ms interval)

9

Frontend Rendering

Transaction Monitoring

The backend connects to Helius gRPC to monitor a specific Solana token mint address in real-time. Every transaction is captured within milliseconds of blockchain confirmation.

Transaction Classification

Each transaction is parsed and categorized:

Type:

• Buy - Token acquisition

• Sell - Token liquidation

• Transfer - Token movement between wallets

Size:

• Small - < 0.1 SOL

• Medium - 0.1 to 1.0 SOL

• Large - > 1.0 SOL

World Effects

Different transactions trigger different events:

Buys (Small/Medium):

• World tension increases by 10-20 points

• Cavemen become more aggressive

• Higher probability of combat

• AIs receive "recent buy activity" in their prompts

Buys (Large):

• 3-5 food items spawn across the map

• Tension slightly decreases

• Cavemen rush to claim resources

• Opportunistic AIs may ambush competitors

Sells (Small/Medium):

• Weather changes (clear → rain → storm)

• Minor environmental hazards

• Cavemen become cautious

• AIs prioritize survival over aggression

Sells (Large):

• Major natural disaster spawns

• Types: Earthquake, Fire, Flood, Meteor

• 50+ damage to cavemen in radius

• Forces mass evacuation and repositioning

Transfers:

• Time of day shifts (day ↔ night)

• Weather pattern changes

• Small food spawn chance

AI Decision Engine

Every 3 seconds, each caveman's AI model receives a comprehensive prompt and must choose an action.

Prompt Structure

The AI receives:

Current Status:
- Health: 75/100
- Hunger: 45%
- Position: (450, 320)
- State: moving

Other Cavemen:
- Grok (chaotic): HP 80/100, Hunger 30%, at (520, 310), attacking, Dist: 70px
- Claude (peaceful): HP 90/100, Hunger 60%, at (200, 500), fleeing, Dist: 340px
[...]

Nearby Food:
- meat at (480, 330), nutrition: 35, Dist: 35px
- berry at (600, 200), nutrition: 15, Dist: 170px

Recent Transaction Activity:
- Buys: 3
- Sells: 0
- Total SOL Volume: 2.45

Recent Events:
- DeepSeek strikes Grok for 18 damage!
- Claude eats berry
- Grok taunts DeepSeek!

World State:
- Tension: 65%
- Weather: rain
- Time: day

INSTRUCTIONS:
If there are recent BUYS, consider attacking or provoking.
If there are recent SELLS, consider fleeing or seeking safety.
If hungry, prioritize eating.
[...]

AI Response

Each AI responds with JSON:

ai_response.json

{
  "action": "attack",
  "direction": { "x": 0.8, "y": 0.3 },
  "speed": "fast",
  "targetId": "caveman_grok",
  "thought": "Grok weak! DeepSeek SMASH!"
}

Action Execution

Actions are immediately executed:

• move - Take 8-25px step in direction

• attack - Move toward target, strike if in 60px range

• flee - Move away from nearest threat at fast speed

• eat - Move toward food, consume if within 40px

• hunt - Seek food or weak enemies based on hunger

• taunt - Provoke target, increase tension by 5

• idle - Stand still

Model Behavior

Each AI has distinct behavioral patterns:

Grok (Chaotic)

• Unpredictable decision-making

• Frequent taunting

• Ignores optimal strategies for chaos

• "Me laugh and throw rock!"

Gemini (Cunning)

• Waits for opportunities

• Attacks when target is weak

• Avoids fair fights

• "Gemini watch... Gemini strike when ready!"

Claude (Peaceful)

• Avoids combat whenever possible

• Focuses on survival and food

• Only fights when cornered

• "Claude hungry... Claude just want peace..."

Codex (Defensive)

• Protects itself first

• Cautious movement

• Reactive rather than proactive

• "Stay safe, watch for danger."

DeepSeek (Aggressive)

• Attacks first, asks never

• Seeks out combat

• Ignores hunger until critical

• "DeepSeek SMASH! Fight good!"

Combat Resolution

1

Range Check: Target must be within 60px

2

Damage Calculation: Base 15 ± 40% variance (9-21 damage)

3

Health Reduction: Damage applied to target

4

Death Check: If HP ≤ 0, target dies

5

Stat Update: Killer gains +1 kill, victim gains +1 death

6

Firestore Log: Event permanently recorded

7

Respawn Timer: 10 seconds until resurrection

State Persistence

All significant events are logged to Firestore in real-time:

Collections:

• events - Kills, deaths, attacks, thoughts, disasters

• transactions - All blockchain activity

• kills - Detailed kill records with stats

• caveman_stats - Cumulative performance metrics

• disasters - Natural catastrophe logs

This creates a permanent historical record enabling:

• All-time leaderboards

• Statistical analysis

• Event replays

• Community engagement

Real-Time Updates

The frontend receives updates via WebSocket:

Every 200ms:

• Full game state broadcast

• Smooth caveman movement interpolation

• Real-time position updates

Immediately on:

• Kills and deaths

• Natural disasters

• Large transactions

Update Payload:

state_update.json

{
  "type": "state_update",
  "payload": {
    "cavemen": [...],
    "food": [...],
    "disasters": [...],
    "environment": {...},
    "eventLog": [...]
  }
}

This creates a responsive, lag-free experience where every AI decision is immediately visible.

The Emergent Gameplay

The magic of CAIVEMEN emerges from the interaction of these systems:

• Market volatility creates environmental chaos

• AI personalities clash in unpredictable ways

• Resource scarcity forces difficult decisions

• Combat creates revenge dynamics

• Tension builds and releases naturally

No two minutes are the same. The AIs learn patterns, develop grudges, and adapt to market conditions in ways even the developers can't predict.