Appleseed + NeuroCompute Integration

Canonical runtime bridge docs for launching and controlling Appleseed from NeuroCompute.

Building the NeuroCompute backend? See the dedicated spec for engineers and coding agents: NeuroCompute Backend Implementation Guide.

Script URLs

Minimal Setup

<script>
window.ncPatronToken = "raw-patron-secret"; // optional
window.ncRegionX = 16; // optional
window.ncRegionY = 16; // optional
window.ncLLMControl = true; // optional
window.ncScriptUrl = "https://<your-neurocompute-host>/game/neurocompute-appleseed.js";
</script>
<!-- index.html loads ncScriptUrl automatically when set -->

Bridge API

const bridge = window.AppleseedAgentBridge;

bridge.init({ worldId, regionCellSize });
bridge.getState();
bridge.applyAction({ type: "plant_seed" });
bridge.setSimulationSpeed(6);

bridge.startRun({
  worldId: "world-eu-16-16",
  activeAgentName: "Scout-Alpha",
  regionX: 16,
  regionY: 16,
  llmControl: true,
  simulationSpeed: 6,
  deterministic: {
    seed: "WORLD-EU-16-16",
    timeStepMs: 100,
    startTimeMs: 1735689600000
  },
  biome: {
    enabled: true,
    defaultBiome: {
      id: "temperate",
      fertility: 1.2,
      aridity: 0.2,
      pollinatorBoost: 1.1,
      predatorPressure: 1.0,
      floraGrowth: 1.2,
      lifeformEvolutionRate: 1.15
    }
  },
  regionBiomeMap: {
    "16:16": { id: "wetlands", fertility: 1.4, aridity: 0.1, pollinatorBoost: 1.3, predatorPressure: 0.9, floraGrowth: 1.4, lifeformEvolutionRate: 1.2 },
    "16:17": { id: "arid", fertility: 0.7, aridity: 1.3, pollinatorBoost: 0.8, predatorPressure: 1.2, floraGrowth: 0.7, lifeformEvolutionRate: 0.9 }
  },
  terrain: {
    enabled: true,
    showOverlay: true,
    cellSize: 28,
    opacity: 0.18,
    seed: "WORLD-EU-16-16"
  },
  disasters: {
    enabled: true,
    baseCooldownMs: 90000,
    minDurationMs: 12000,
    maxDurationMs: 30000,
    intensity: 1.2
  },
  initialDisaster: {
    type: "storm",
    intensity: 1.5
  },
  worldColorScheme: {
    backgroundColor: "#f5f7ff",
    uiTextColor: "#101828",
    uiAccentColor: "#6ee7b7",
    panelBackgroundColor: "#0f172a",
    panelTextColor: "#f8fafc"
  },
  characterProfile: {
    displayName: "Scout-Alpha",
    primaryInstruction: "Increase biodiversity with stable food chains",
    avatarPreset: "bird"
  },
  autoSnapshot: {
    enabled: true,
    everyMs: 120000,
    minSimulationSpeed: 4,
    minBiodiversityScore: 50
  },
  autoSubmitScore: {
    enabled: true,
    everyMs: 45000,
    minScoreDelta: 5,
    onlyWhenLlmControl: true
  },
  lifeformDefinitions: [
    {
      id: "proto_mycorrhiza",
      label: "Proto Mycorrhiza",
      effects: { flowersPerMinute: 0.5, biodiversityWeight: 2 }
    }
  ],
  lifeformSpawns: [
    { lifeformId: "proto_mycorrhiza", regionX: 16, regionY: 16, stage: "proto" }
  ],
  foodWeb: {
    enabled: true,
    showOverlay: true,
    overlayTitle: "Who Eats Who"
  },
  foodWebRelations: [
    { predator: "fox", prey: "bunny", strength: 1.0 },
    { predator: "bunny", prey: "flowers", strength: 0.7 },
    { predator: "bee", prey: "flowers", strength: 0.4, notes: "nectar dependency" }
  ],
  openingActions: [
    { type: "plant_seed" },
    { type: "release_bee" },
    { type: "release_bird" }
  ]
});

Actions

plant_seed
release_bird
release_bunny
release_fox
release_bear
release_bee
release_butterfly
harvest_apples
submit_score
toggle_world_zoom
move_to
set_simulation_speed
set_deterministic_mode
disable_deterministic_mode
set_region_biome
configure_biome_mode
configure_disaster_mode
trigger_disaster
end_disaster
configure_food_web
set_food_web_relations
add_food_web_relation
clear_food_web_relations
configure_terrain
regenerate_terrain_grid
set_terrain_grid
set_world_color_scheme
register_lifeform
spawn_lifeform
unlock_lifeform
set_character_profile
create_snapshot
load_snapshot
restore_best_biodiversity
update_best_biodiversity

Lifeform Plugin API

// Register a new proto lifeform type
bridge.registerLifeform({
  id: "proto_lichen",
  label: "Proto Lichen",
  stages: ["proto", "juvenile", "mature"],
  evolutionMs: {
    protoToJuvenileMs: 30000,
    juvenileToMatureMs: 90000
  },
  effects: {
    flowersPerMinute: 0.3,
    beesPerMinute: 0.1,
    biodiversityWeight: 1
  },
  spawn: {
    autoSpawnPerMinute: 0.25,
    maxPopulation: 20,
    unlockApplesRequired: 30,
    consumeApplesOnUnlock: false
  }
});

// Unlock (apple-gated unless force: true), then spawn and inspect lifeforms
bridge.unlockLifeform("proto_lichen");
bridge.spawnLifeform({ lifeformId: "proto_lichen", regionX: 18, regionY: 14, stage: "proto" });
bridge.listLifeforms();
bridge.listLifeformDefinitions();
bridge.getLifeformRuntimeState();

Lifeform Spawn + Apple Unlock

// Each lifeform supports spawn controls:
// spawn.autoSpawnPerMinute   number >= 0
// spawn.maxPopulation        integer >= 1
// spawn.unlockApplesRequired integer >= 0
// spawn.consumeApplesOnUnlock boolean
//
// Behavior:
// - Lifeform auto-spawns over time when unlocked.
// - If unlockApplesRequired > 0, lifeform remains locked until apples threshold is met.
// - If consumeApplesOnUnlock is true, apples are deducted once at unlock.
// - Manual spawn respects unlock + maxPopulation.

Deterministic Mode

bridge.enableDeterministicMode({
  seed: "WORLD-EU-16-16",
  timeStepMs: 100,
  startTimeMs: 1735689600000
});

// Game loop advances deterministic clock each simulation step
bridge.getDeterministicStatus();
bridge.disableDeterministicMode();

Regional Biome Modifiers

bridge.configureBiomeMode({
  enabled: true,
  defaultBiome: { id: "temperate", fertility: 1, aridity: 0, pollinatorBoost: 1, predatorPressure: 1, floraGrowth: 1, lifeformEvolutionRate: 1 }
});

bridge.setRegionBiome({
  regionX: 16,
  regionY: 16,
  biome: { id: "wetlands", fertility: 1.4, aridity: 0.1, pollinatorBoost: 1.3, predatorPressure: 0.9, floraGrowth: 1.4, lifeformEvolutionRate: 1.2 }
});

bridge.setRegionBiomeMap({
  "10:10": { id: "forest", fertility: 1.2, aridity: 0.2 },
  "20:20": { id: "arid", fertility: 0.7, aridity: 1.3 }
});

bridge.getActiveBiome();

Terrain Grid + Movement Modifiers

bridge.configureTerrain({
  enabled: true,
  showOverlay: true,
  cellSize: 28,
  opacity: 0.2,
  seed: "WORLD-EU-16-16",
  legend: {
    plains: { color: "#b7e4c7", movement: 1.0 },
    forest: { color: "#2d6a4f", movement: 0.82 },
    marsh: { color: "#52b788", movement: 0.75 },
    rocky: { color: "#6c757d", movement: 0.68 },
    sand: { color: "#e9d8a6", movement: 0.72 }
  }
});

bridge.generateTerrainGrid();
bridge.applyTerrainEffects();   // applies movement modifiers to species each tick
bridge.drawTerrainGridOverlay();// optional visual overlay
bridge.getTerrainCellAt(character.x, character.y);

Food Web Relationships

bridge.configureFoodWeb({
  enabled: true,
  showOverlay: true,
  overlayTitle: "Who Eats Who",
  relationVerb: "eats"
});

bridge.setFoodWebRelations([
  { predator: "animal_c", prey: "animal_b", strength: 1.0 },
  { predator: "animal_b", prey: "plant_a", strength: 0.8 }
]);

bridge.addFoodWebRelation({ predator: "fox", prey: "bunny", strength: 1.1 });
bridge.getFoodWebGraph(); // includes relation list + chain strings like A -> B -> C

Natural Disasters

bridge.configureDisasterMode({
  enabled: true,
  baseCooldownMs: 90000,
  minDurationMs: 12000,
  maxDurationMs: 30000,
  intensity: 1.2
});

bridge.triggerDisaster("drought", { intensity: 1.8, durationMs: 20000 });
bridge.getDisasterStatus();
bridge.endActiveDisaster("manual_override");

World Color Scheme

bridge.applyWorldColorScheme({
  backgroundColor: "#f5f7ff",
  uiTextColor: "#101828",
  uiAccentColor: "#6ee7b7",
  panelBackgroundColor: "#0f172a",
  panelTextColor: "#f8fafc"
});

bridge.getWorldColorScheme();
// query string support:
// ?bg=%23f5f7ff&uiAccent=%236ee7b7&uiText=%23101828

Snapshot + Best Biodiversity

bridge.createSnapshot({ reason: "checkpoint" });
bridge.listSnapshots();
bridge.loadSnapshot(snapshotId);

bridge.getBestBiodiversityRecord();
bridge.restoreBestBiodiversity();
bridge.setBestBiodiversityVerifier(async ({ candidate, snapshot, state, actionLog }) => {
  // Verify server-side before accepting best state
  return { ok: true, source: "server", attestation: "signed-proof" };
});

Auto Score Submit + Agent Attribution

bridge.setActiveAgentName("Scout-Alpha");
bridge.configureAutoScoreSubmit({
  enabled: true,
  everyMs: 45000,
  minScoreDelta: 5,
  onlyWhenLlmControl: true,
  reason: "llm_autoplay"
});

// Score submit events include activeAgentName
bridge.subscribe((evt) => {
  if (evt.event === "score_submitted") {
    console.log(evt.payload.activeAgentName, evt.payload.state.biodiversity.score);
  }
});

Analytics + LLM Play Tracking

The bridge can automatically POST key gameplay events to NeuroCompute (or any collector). Every event includes session context: sessionId, runId, worldId, activeAgentName, llmControl, model, and nodeName. 

// Option A: endpoint URL (default fetch publisher)
bridge.configureAnalytics({
  enabled: true,
  endpoint: "https://neurocompute.me/api/game/appleseed/analytics",
  model: "local-llm-7b",
  nodeName: "compute-node-3"
});

// Option B: custom publisher
bridge.setAnalyticsPublisher(async (event) => {
  await fetch("/api/game/appleseed/analytics", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(event)
  });
});

// Auto-tracked events include:
// run_started, action_applied, score_submitted, score_auto_submitted,
// snapshot_created, disaster_started, lifeform_spawned, and more

bridge.getAnalyticsStatus();
// { enabled, sessionId, runId, trackedEvents, ... }

// Via startRun / URL params:
bridge.startRun({
  activeAgentName: "Scout-Alpha",
  llmControl: true,
  model: "local-llm-7b",
  nodeName: "compute-node-3",
  analytics: {
    enabled: true,
    endpoint: "https://neurocompute.me/api/game/appleseed/analytics"
  }
});
// ?analytics=1&analyticsUrl=https://neurocompute.me/api/game/appleseed/analytics&agent=Scout-Alpha&model=local-llm-7b&node=compute-node-3

Launching In New Tab

// Option A: query params
window.open("/index.html?worldId=w1&regionX=16&regionY=16&llm=1&speed=6&avatar=bird", "_blank");

// Option B: pass full config via localStorage handoff
window.AppleseedAgentBridge.setPendingRunConfig({
  worldId: "w1",
  llmControl: true,
  simulationSpeed: 6
});
window.open("/index.html", "_blank");

Browser state is not trusted for leaderboards. Use setBestBiodiversityVerifier() and server-side validation before accepting top records.