solanapolis 1.0.0

package/convex/npcCarAgents.ts

@@ -0,0 +1,415 @@
+// @ts-nocheck
+import { v } from 'convex/values';
+import OpenAI from 'openai';
+import {
+    internalAction,
+    internalMutation,
+    internalQuery,
+    mutation,
+    query,
+} from './_generated/server';
+import { internal } from './_generated/api';
+
+const AGENT_DECISION_INTERVAL_MS = 45_000;
+const MAX_SYNC_CARS = 48;
+const MAX_TICK_AGENTS = 12;
+
+type AgentStyle = 'calm' | 'aggressive' | 'explorer' | 'cautious';
+type RoutePreference = 'home' | 'explore' | 'mixed';
+type DecisionSource = 'openrouter' | 'fallback';
+
+type AgentDecision = {
+    style: AgentStyle;
+    mood: string;
+    thought: string;
+    speedMultiplier: number;
+    routePreference: RoutePreference;
+    source: DecisionSource;
+};
+
+const styleValidator = v.union(
+    v.literal('calm'),
+    v.literal('aggressive'),
+    v.literal('explorer'),
+    v.literal('cautious'),
+);
+
+const routePreferenceValidator = v.union(
+    v.literal('home'),
+    v.literal('explore'),
+    v.literal('mixed'),
+);
+
+const sourceValidator = v.union(v.literal('openrouter'), v.literal('fallback'));
+
+const syncCarValidator = v.object({
+    walletAddress: v.string(),
+    displayName: v.optional(v.string()),
+    blockRow: v.optional(v.number()),
+    blockCol: v.optional(v.number()),
+});
+
+function clamp(value: number, min: number, max: number) {
+    return Math.max(min, Math.min(max, value));
+}
+
+function hashString(input: string) {
+    let h = 2166136261;
+    for (let i = 0; i < input.length; i++) {
+        h ^= input.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return Math.abs(h >>> 0);
+}
+
+function pick<T>(arr: T[], seed: number) {
+    return arr[seed % arr.length];
+}
+
+function normalizeThought(text: string) {
+    return text.replace(/\s+/g, ' ').trim().slice(0, 120) || 'Cruising through Solanapolis.';
+}
+
+function parseJsonObject(text: string): Record<string, unknown> | null {
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start < 0 || end < 0 || end <= start) return null;
+    try {
+        return JSON.parse(text.slice(start, end + 1)) as Record<string, unknown>;
+    } catch {
+        return null;
+    }
+}
+
+function fallbackDecision(agent: { walletAddress: string; displayName?: string | null }, now: number): AgentDecision {
+    const tick = Math.floor(now / AGENT_DECISION_INTERVAL_MS);
+    const seed = hashString(`${agent.walletAddress}:${tick}`);
+
+    const style = pick<AgentStyle>(['calm', 'aggressive', 'explorer', 'cautious'], seed + 7);
+    const routePreference =
+        style === 'explorer'
+            ? 'explore'
+            : style === 'cautious'
+                ? 'home'
+                : pick<RoutePreference>(['home', 'mixed', 'explore'], seed + 13);
+
+    const mood = pick(
+        ['focused', 'curious', 'competitive', 'chill', 'alert', 'determined'],
+        seed + 23,
+    );
+
+    const thoughts = [
+        'Avoiding traffic near the central skyline.',
+        'Scanning for faster routes near the waterfront.',
+        'Keeping a safe line between the tower blocks.',
+        'Exploring side roads for better visibility.',
+        'Maintaining pace and watching intersections.',
+        'Cruising smoothly through Solanapolis avenues.',
+    ];
+
+    const styleBoost: Record<AgentStyle, number> = {
+        calm: 0.95,
+        aggressive: 1.22,
+        explorer: 1.08,
+        cautious: 0.82,
+    };
+
+    const variance = ((seed % 21) - 10) / 100; // -0.10..0.10
+    const speedMultiplier = clamp(styleBoost[style] + variance, 0.6, 1.6);
+
+    return {
+        style,
+        routePreference,
+        mood,
+        thought: normalizeThought(pick(thoughts, seed + 31)),
+        speedMultiplier,
+        source: 'fallback',
+    };
+}
+
+function coerceStyle(value: unknown, fallback: AgentStyle): AgentStyle {
+    if (value === 'calm' || value === 'aggressive' || value === 'explorer' || value === 'cautious') {
+        return value;
+    }
+    return fallback;
+}
+
+function coerceRoutePreference(value: unknown, fallback: RoutePreference): RoutePreference {
+    if (value === 'home' || value === 'explore' || value === 'mixed') return value;
+    return fallback;
+}
+
+function coerceNumber(value: unknown, fallback: number) {
+    if (typeof value !== 'number' || Number.isNaN(value)) return fallback;
+    return value;
+}
+
+async function getOpenRouterDecision(agent: {
+    walletAddress: string;
+    displayName?: string | null;
+    persona?: string | null;
+}): Promise<AgentDecision | null> {
+    const apiKey = process.env.OPENROUTER_API_KEY || process.env.OPENAI_API_KEY;
+    if (!apiKey) return null;
+
+    const usingOpenRouter = !!process.env.OPENROUTER_API_KEY;
+    const model =
+        process.env.OPENROUTER_AGENT_MODEL ||
+        process.env.OPENROUTER_MODEL ||
+        (usingOpenRouter ? 'openai/gpt-4o-mini' : 'gpt-4.1-mini');
+
+    const client = new OpenAI({
+        apiKey,
+        baseURL: usingOpenRouter ? 'https://openrouter.ai/api/v1' : undefined,
+    });
+
+    const completion = await client.chat.completions.create({
+        model,
+        temperature: 0.8,
+        max_tokens: 180,
+        messages: [
+            {
+                role: 'system',
+                content:
+                    'You are an NPC driving-policy planner for Solanapolis. Return ONLY a JSON object with keys: style, mood, thought, speedMultiplier, routePreference. style must be one of calm/aggressive/explorer/cautious. routePreference must be one of home/explore/mixed. speedMultiplier must be a number between 0.6 and 1.6. thought should be short (max 120 chars).',
+            },
+            {
+                role: 'user',
+                content: `Wallet: ${agent.walletAddress}\nDisplay Name: ${agent.displayName || 'Unknown'}\nPersona: ${agent.persona || 'City driver'}\nPick a fresh driving decision for the next 45 seconds.`,
+            },
+        ],
+        response_format: { type: 'json_object' },
+    });
+
+    const text = completion.choices[0]?.message?.content ?? '';
+    const parsed = parseJsonObject(text);
+    if (!parsed) return null;
+
+    const fallback = fallbackDecision(agent, Date.now());
+
+    return {
+        style: coerceStyle(parsed.style, fallback.style),
+        routePreference: coerceRoutePreference(parsed.routePreference, fallback.routePreference),
+        mood:
+            typeof parsed.mood === 'string' && parsed.mood.trim().length > 0
+                ? parsed.mood.trim().slice(0, 40)
+                : fallback.mood,
+        thought:
+            typeof parsed.thought === 'string' ? normalizeThought(parsed.thought) : fallback.thought,
+        speedMultiplier: clamp(coerceNumber(parsed.speedMultiplier, fallback.speedMultiplier), 0.6, 1.6),
+        source: 'openrouter',
+    };
+}
+
+function defaultPersona(walletAddress: string) {
+    const seed = hashString(walletAddress);
+    const traits = ['precision-focused', 'route-optimizing', 'social', 'risk-aware', 'explorer'];
+    const goals = ['maintain flow', 'avoid collisions', 'scan for shortcuts', 'patrol city blocks'];
+    return `A ${pick(traits, seed)} autonomous city driver that tries to ${pick(goals, seed + 5)}.`;
+}
+
+export const syncAgents = mutation({
+    args: {
+        cars: v.array(syncCarValidator),
+    },
+    handler: async (ctx, args) => {
+        const now = Date.now();
+        const uniqueCars = new Map<string, (typeof args.cars)[number]>();
+        for (const car of args.cars.slice(0, MAX_SYNC_CARS)) {
+            uniqueCars.set(car.walletAddress, car);
+        }
+
+        for (const [, car] of uniqueCars) {
+            const existing = (await ctx.db
+                .query('npcCarAgents' as any)
+                .withIndex('by_wallet', (q) => q.eq('walletAddress', car.walletAddress))
+                .first()) as any;
+
+            if (existing) {
+                await ctx.db.patch(existing._id, {
+                    displayName: car.displayName ?? existing.displayName,
+                    homeBlockRow: typeof car.blockRow === 'number' ? car.blockRow : existing.homeBlockRow,
+                    homeBlockCol: typeof car.blockCol === 'number' ? car.blockCol : existing.homeBlockCol,
+                    lastSyncedAt: now,
+                    active: true,
+                });
+            } else {
+                const fallback = fallbackDecision({ walletAddress: car.walletAddress, displayName: car.displayName }, now);
+                await ctx.db.insert('npcCarAgents' as any, {
+                    walletAddress: car.walletAddress,
+                    displayName: car.displayName,
+                    homeBlockRow: car.blockRow,
+                    homeBlockCol: car.blockCol,
+                    persona: defaultPersona(car.walletAddress),
+                    style: fallback.style,
+                    mood: fallback.mood,
+                    thought: fallback.thought,
+                    speedMultiplier: fallback.speedMultiplier,
+                    routePreference: fallback.routePreference,
+                    source: 'fallback',
+                    active: true,
+                    lastDecisionAt: now - AGENT_DECISION_INTERVAL_MS,
+                    lastSyncedAt: now,
+                    updatedAt: now,
+                });
+            }
+        }
+
+        await ctx.scheduler.runAfter(0, (internal as any).npcCarAgents.tickDueAgents, {
+            maxAgents: MAX_TICK_AGENTS,
+        });
+
+        return { synced: uniqueCars.size };
+    },
+});
+
+export const listForWallets = query({
+    args: {
+        wallets: v.array(v.string()),
+    },
+    handler: async (ctx, args) => {
+        const out: Record<
+            string,
+            {
+                displayName: string | null;
+                style: AgentStyle;
+                mood: string;
+                thought: string;
+                speedMultiplier: number;
+                routePreference: RoutePreference;
+                updatedAt: number;
+                source: DecisionSource;
+            }
+        > = {};
+
+        const uniqueWallets = [...new Set(args.wallets)].slice(0, MAX_SYNC_CARS);
+        for (const walletAddress of uniqueWallets) {
+            const row = (await ctx.db
+                .query('npcCarAgents' as any)
+                .withIndex('by_wallet', (q) => q.eq('walletAddress', walletAddress))
+                .first()) as any;
+
+            if (!row) continue;
+            out[walletAddress] = {
+                displayName: row.displayName ?? null,
+                style: row.style,
+                mood: row.mood,
+                thought: row.thought,
+                speedMultiplier: row.speedMultiplier,
+                routePreference: row.routePreference,
+                updatedAt: row.updatedAt,
+                source: row.source,
+            };
+        }
+
+        return out;
+    },
+});
+
+export const getDueAgents = internalQuery({
+    args: {
+        now: v.number(),
+        limit: v.number(),
+    },
+    handler: async (ctx, args) => {
+        const dueBefore = args.now - AGENT_DECISION_INTERVAL_MS;
+        const limit = clamp(args.limit, 1, MAX_TICK_AGENTS);
+        const rows = (await ctx.db
+            .query('npcCarAgents' as any)
+            .withIndex('by_active_decision', (q: any) => q.eq('active', true).lte('lastDecisionAt', dueBefore))
+            .take(limit)) as any[];
+
+        return rows.map((row) => ({
+            _id: row._id,
+            walletAddress: row.walletAddress as string,
+            displayName: (row.displayName as string | undefined) ?? null,
+            persona: (row.persona as string | undefined) ?? null,
+        }));
+    },
+});
+
+export const applyDecision = internalMutation({
+    args: {
+        agentId: v.id('npcCarAgents'),
+        style: styleValidator,
+        mood: v.string(),
+        thought: v.string(),
+        speedMultiplier: v.number(),
+        routePreference: routePreferenceValidator,
+        source: sourceValidator,
+        decidedAt: v.number(),
+    },
+    handler: async (ctx, args) => {
+        const agent = (await ctx.db.get(args.agentId)) as any;
+        if (!agent) return;
+
+        await ctx.db.patch(args.agentId, {
+            style: args.style,
+            mood: args.mood,
+            thought: normalizeThought(args.thought),
+            speedMultiplier: clamp(args.speedMultiplier, 0.6, 1.6),
+            routePreference: args.routePreference,
+            source: args.source,
+            lastDecisionAt: args.decidedAt,
+            updatedAt: args.decidedAt,
+        });
+
+        await ctx.db.insert('npcCarDecisionLog' as any, {
+            walletAddress: agent.walletAddress,
+            style: args.style,
+            mood: args.mood,
+            thought: normalizeThought(args.thought),
+            speedMultiplier: clamp(args.speedMultiplier, 0.6, 1.6),
+            routePreference: args.routePreference,
+            source: args.source,
+            decisionAt: args.decidedAt,
+        });
+    },
+});
+
+export const tickDueAgents = internalAction({
+    args: {
+        maxAgents: v.optional(v.number()),
+    },
+    handler: async (ctx, args) => {
+        const now = Date.now();
+        const maxAgents = clamp(args.maxAgents ?? MAX_TICK_AGENTS, 1, MAX_TICK_AGENTS);
+
+        const dueAgents = (await ctx.runQuery((internal as any).npcCarAgents.getDueAgents, {
+            now,
+            limit: maxAgents,
+        })) as Array<{
+            _id: string;
+            walletAddress: string;
+            displayName?: string | null;
+            persona?: string | null;
+        }>;
+
+        let processed = 0;
+        for (const agent of dueAgents) {
+            const fallback = fallbackDecision(agent, now);
+            let decision = fallback;
+            try {
+                const llmDecision = await getOpenRouterDecision(agent);
+                if (llmDecision) decision = llmDecision;
+            } catch (err) {
+                console.warn('[npcCarAgents] OpenRouter decision failed, falling back:', err);
+            }
+
+            await ctx.runMutation((internal as any).npcCarAgents.applyDecision, {
+                agentId: agent._id,
+                style: decision.style,
+                mood: decision.mood,
+                thought: decision.thought,
+                speedMultiplier: decision.speedMultiplier,
+                routePreference: decision.routePreference,
+                source: decision.source,
+                decidedAt: now,
+            });
+
+            processed += 1;
+        }
+
+        return { processed };
+    },
+});

package/convex/schema.ts

@@ -0,0 +1,61 @@
+import { defineSchema, defineTable } from "convex/server";
+import { StreamIdValidator } from "@convex-dev/persistent-text-streaming";
+import { v } from "convex/values";
+import { agentTables } from "./agent/schema";
+import { aiTownTables } from "./aiTown/schema";
+import { conversationId, playerId } from "./aiTown/ids";
+import { engineTables } from "./engine/schema";
+
+export default defineSchema({
+  // === Heliopolis City Chat ===
+  chat_messages: defineTable({
+    wallet_address: v.string(),
+    display_name: v.optional(v.string()),
+    message: v.string(),
+    is_ai: v.optional(v.boolean()),
+    responseStreamId: v.optional(StreamIdValidator),
+  }),
+
+  // === AI Town: NPC Messages ===
+  messages: defineTable({
+    conversationId,
+    messageUuid: v.string(),
+    author: playerId,
+    text: v.string(),
+    worldId: v.optional(v.id("worlds")),
+  })
+    .index("conversationId", ["worldId", "conversationId"])
+    .index("messageUuid", ["conversationId", "messageUuid"]),
+
+  // === AI Town: Background Music ===
+  music: defineTable({
+    storageId: v.string(),
+    type: v.union(v.literal("background"), v.literal("player")),
+  }),
+
+  // === NPC Car Agents (LLM-driven driving behavior) ===
+  npcCarAgents: defineTable({
+    walletAddress: v.string(),
+    displayName: v.optional(v.string()),
+    homeBlockRow: v.optional(v.number()),
+    homeBlockCol: v.optional(v.number()),
+    persona: v.optional(v.string()),
+    style: v.string(),
+    mood: v.string(),
+    thought: v.string(),
+    speedMultiplier: v.number(),
+    routePreference: v.string(),
+    source: v.string(),
+    active: v.boolean(),
+    lastDecisionAt: v.number(),
+    lastSyncedAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_wallet", ["walletAddress"])
+    .index("by_active_decision", ["active", "lastDecisionAt"]),
+
+  // === AI Town: Engine + Game + Agent tables ===
+  ...engineTables,
+  ...aiTownTables,
+  ...agentTables,
+});

package/convex/streaming.ts

@@ -0,0 +1,23 @@
+import {
+  PersistentTextStreaming,
+  StreamId,
+  StreamIdValidator,
+} from "@convex-dev/persistent-text-streaming";
+import { components } from "./_generated/api";
+import { query } from "./_generated/server";
+
+export const streamingComponent = new PersistentTextStreaming(
+  components.persistentTextStreaming,
+);
+
+export const getStreamBody = query({
+  args: {
+    streamId: StreamIdValidator,
+  },
+  handler: async (ctx, args) => {
+    return await streamingComponent.getStreamBody(
+      ctx,
+      args.streamId as StreamId,
+    );
+  },
+});

package/convex/testing.ts

@@ -0,0 +1,202 @@
+import { Id, TableNames } from './_generated/dataModel';
+import { internal } from './_generated/api';
+import {
+  DatabaseReader,
+  internalAction,
+  internalMutation,
+  mutation,
+  query,
+} from './_generated/server';
+import { v } from 'convex/values';
+import schema from './schema';
+import { DELETE_BATCH_SIZE } from './constants';
+import { kickEngine, startEngine, stopEngine } from './aiTown/main';
+import { insertInput } from './aiTown/insertInput';
+import { fetchEmbedding } from './util/llm';
+import { chatCompletion } from './util/llm';
+import { startConversationMessage } from './agent/conversation';
+import { GameId } from './aiTown/ids';
+
+// Clear all of the tables except for the embeddings cache.
+const excludedTables: Array<TableNames> = ['embeddingsCache'];
+
+export const wipeAllTables = internalMutation({
+  handler: async (ctx) => {
+    for (const tableName of Object.keys(schema.tables)) {
+      if (excludedTables.includes(tableName as TableNames)) {
+        continue;
+      }
+      await ctx.scheduler.runAfter(0, internal.testing.deletePage, { tableName, cursor: null });
+    }
+  },
+});
+
+export const deletePage = internalMutation({
+  args: {
+    tableName: v.string(),
+    cursor: v.union(v.string(), v.null()),
+  },
+  handler: async (ctx, args) => {
+    const results = await ctx.db
+      .query(args.tableName as TableNames)
+      .paginate({ cursor: args.cursor, numItems: DELETE_BATCH_SIZE });
+    for (const row of results.page) {
+      await ctx.db.delete(row._id);
+    }
+    if (!results.isDone) {
+      await ctx.scheduler.runAfter(0, internal.testing.deletePage, {
+        tableName: args.tableName,
+        cursor: results.continueCursor,
+      });
+    }
+  },
+});
+
+export const kick = internalMutation({
+  handler: async (ctx) => {
+    const { worldStatus } = await getDefaultWorld(ctx.db);
+    await kickEngine(ctx, worldStatus.worldId);
+  },
+});
+
+export const stopAllowed = query({
+  handler: async () => {
+    return !process.env.STOP_NOT_ALLOWED;
+  },
+});
+
+export const stop = mutation({
+  handler: async (ctx) => {
+    if (process.env.STOP_NOT_ALLOWED) throw new Error('Stop not allowed');
+    const { worldStatus, engine } = await getDefaultWorld(ctx.db);
+    if (worldStatus.status === 'inactive' || worldStatus.status === 'stoppedByDeveloper') {
+      if (engine.running) {
+        throw new Error(`Engine ${engine._id} isn't stopped?`);
+      }
+      console.debug(`World ${worldStatus.worldId} is already inactive`);
+      return;
+    }
+    console.log(`Stopping engine ${engine._id}...`);
+    await ctx.db.patch(worldStatus._id, { status: 'stoppedByDeveloper' });
+    await stopEngine(ctx, worldStatus.worldId);
+  },
+});
+
+export const resume = mutation({
+  handler: async (ctx) => {
+    const { worldStatus, engine } = await getDefaultWorld(ctx.db);
+    if (worldStatus.status === 'running') {
+      if (!engine.running) {
+        throw new Error(`Engine ${engine._id} isn't running?`);
+      }
+      console.debug(`World ${worldStatus.worldId} is already running`);
+      return;
+    }
+    console.log(
+      `Resuming engine ${engine._id} for world ${worldStatus.worldId} (state: ${worldStatus.status})...`,
+    );
+    await ctx.db.patch(worldStatus._id, { status: 'running' });
+    await startEngine(ctx, worldStatus.worldId);
+  },
+});
+
+export const archive = internalMutation({
+  handler: async (ctx) => {
+    const { worldStatus, engine } = await getDefaultWorld(ctx.db);
+    if (engine.running) {
+      throw new Error(`Engine ${engine._id} is still running!`);
+    }
+    console.log(`Archiving world ${worldStatus.worldId}...`);
+    await ctx.db.patch(worldStatus._id, { isDefault: false });
+  },
+});
+
+async function getDefaultWorld(db: DatabaseReader) {
+  const worldStatus = await db
+    .query('worldStatus')
+    .filter((q) => q.eq(q.field('isDefault'), true))
+    .first();
+  if (!worldStatus) {
+    throw new Error('No default world found');
+  }
+  const engine = await db.get(worldStatus.engineId);
+  if (!engine) {
+    throw new Error(`Engine ${worldStatus.engineId} not found`);
+  }
+  return { worldStatus, engine };
+}
+
+export const debugCreatePlayers = internalMutation({
+  args: {
+    numPlayers: v.number(),
+  },
+  handler: async (ctx, args) => {
+    const { worldStatus } = await getDefaultWorld(ctx.db);
+    for (let i = 0; i < args.numPlayers; i++) {
+      const inputId = await insertInput(ctx, worldStatus.worldId, 'join', {
+        name: `Robot${i}`,
+        description: `This player is a robot.`,
+        character: `f${1 + (i % 8)}`,
+      });
+    }
+  },
+});
+
+export const randomPositions = internalMutation({
+  handler: async (ctx) => {
+    const { worldStatus } = await getDefaultWorld(ctx.db);
+    const map = await ctx.db
+      .query('maps')
+      .withIndex('worldId', (q) => q.eq('worldId', worldStatus.worldId))
+      .unique();
+    if (!map) {
+      throw new Error(`No map for world ${worldStatus.worldId}`);
+    }
+    const world = await ctx.db.get(worldStatus.worldId);
+    if (!world) {
+      throw new Error(`No world for world ${worldStatus.worldId}`);
+    }
+    for (const player of world.players) {
+      await insertInput(ctx, world._id, 'moveTo', {
+        playerId: player.id,
+        destination: {
+          x: 1 + Math.floor(Math.random() * (map.width - 2)),
+          y: 1 + Math.floor(Math.random() * (map.height - 2)),
+        },
+      });
+    }
+  },
+});
+
+export const testEmbedding = internalAction({
+  args: { input: v.string() },
+  handler: async (_ctx, args) => {
+    return await fetchEmbedding(args.input);
+  },
+});
+
+export const testCompletion = internalAction({
+  args: {},
+  handler: async (ctx, args) => {
+    return await chatCompletion({
+      messages: [
+        { content: 'You are helpful', role: 'system' },
+        { content: 'Where is pizza?', role: 'user' },
+      ],
+    });
+  },
+});
+
+export const testConvo = internalAction({
+  args: {},
+  handler: async (ctx, args) => {
+    const a: any = (await startConversationMessage(
+      ctx,
+      'm1707m46wmefpejw1k50rqz7856qw3ew' as Id<'worlds'>,
+      'c:115' as GameId<'conversations'>,
+      'p:0' as GameId<'players'>,
+      'p:6' as GameId<'players'>,
+    )) as any;
+    return await a.readAll();
+  },
+});