local-agents

local-agents

Local Agents is an add-on for Godot 4.5 to run LLMs locally in games

Stars: 73

Visit
 screenshot

Local Agents is a Godot project focusing on a deterministic 3D simulation with ecology, mammals, and chemical smell fields. It includes features like edible plants, rabbits, smell behavior, wind simulation, and camera controls. The project uses shared voxel infrastructure for simulation and chemistry-driven smell modeling. It also features world generation, runtime simulation, rendering with GPU shaders, and integrated demo controls. The project is designed for scene-first and resource-driven runtime, preferring voxel-native simulation over RigidBody3D.

README:

Local Agents (Godot)

Current project focus is a deterministic 3D simulation vertical slice with ecology, mammals, and inspectable chemical smell fields.

Current Scope

  • PlantRabbitField scene as the active sandbox.
  • Edible plants as small thin green capsules with staged growth and flowering.
  • Rabbits as white spheres that forage, flee, eat plants, digest seeds, and reseed via poop.
  • Mammal smell behavior generalized via profile resources (rabbits and villagers share the same contract, with different sensitivities).
  • Smell and wind simulated on a shared sparse voxel field (clean break from active hex runtime path).
  • Click selection + inspector panel + spawn UI (targeted spawn and random spawn).
  • Camera controls for simulation editing (orbit/pan/zoom + right-click pan).
  • Debug overlays for smell, wind, and temperature with translucent voxel rendering.

Core Runtime Model

Shared Voxel Infrastructure

  • addons/local_agents/simulation/VoxelGridSystem.gd
  • Used by:
    • SmellFieldSystem
    • WindFieldSystem
    • EcologyController edible indexing/debug views

Chemistry-Driven Smell

Plants and mammals emit chemical mixtures, not generic food/danger tags.

Examples currently modeled:

  • Plant/flower compounds: hexanal, cis_3_hexenol, linalool, benzyl_acetate, phenylacetaldehyde, geraniol, methyl_salicylate.
  • Taste/defense compounds: sugars, tannins, alkaloids.
  • Mammal/waste compounds: ammonia, butyric_acid, 2_heptanone.

Mammals convert these into behavior using weighted sensitivity profiles (MammalProfileResource).

Wind and Decay

  • Smell advects with wind direction/intensity when enabled.
  • Smell decays over time.
  • Rain increases decay.
  • Wind field evolves spatially from base wind + terrain/temperature effects.

Field Controls

Inside PlantRabbitField:

  • LMB: select actor / place spawn (when spawn mode active)
  • Esc or RMB: cancel spawn mode back to select
  • Spawn mode auto-resets to select after placing one entity
  • Mouse wheel: zoom
  • MMB drag: orbit
  • Shift + MMB drag: pan
  • RMB drag: pan

Bottom HUD supports:

  • Select
  • Spawn Plant
  • Spawn Rabbit
  • Spawn Random with user-set counts

Right HUD shows inspector payload for selected entities.

Debug Views

Debug overlay roots:

  • SmellDebug
  • WindDebug
  • TemperatureDebug

Rendering style:

  • Smell: translucent chemical voxel overlays.
  • Temperature: translucent blue-to-red voxel spectrum.
  • Wind: translucent directional vector markers.

Key Scenes and Scripts

  • Scene: addons/local_agents/scenes/simulation/PlantRabbitField.tscn
  • Scene: addons/local_agents/scenes/demos/VoxelWorldDemo.tscn (seed + sliders + visible baked flowmap arrows)
  • Controller: addons/local_agents/scenes/simulation/controllers/PlantRabbitField.gd
  • Ecology orchestration: addons/local_agents/scenes/simulation/controllers/EcologyController.gd
  • Plant actor: addons/local_agents/scenes/simulation/actors/EdiblePlantCapsule.gd
  • Rabbit actor: addons/local_agents/scenes/simulation/actors/RabbitSphere.gd
  • Villager actor: addons/local_agents/scenes/simulation/actors/VillagerCapsule.gd

Voxel Simulator Features

World Generation

  • FastNoiseLite-based 3D voxel terrain generation with deterministic seeds.
  • Minecraft-style stratified block stacks: topsoil/subsoil/stone/water with caves.
  • Multiple terrain/resource block types in generated columns and block rows (soil variants + ore blocks).
  • Deterministic baked flow maps (downhill direction, accumulation, channel strength).

Runtime Simulation

  • Deterministic voxel transform pipeline with generic transport/thermal/mechanics/failure passes (single runtime authority).
  • Transform snapshots and diagnostics are stage-agnostic contract payloads (transform_snapshot, transform_diagnostics) for runtime/bridge consumers.
  • Preset-based emitters drive destruction/environment edit emission; profile switches are preset changes, not runtime-stack swaps.
  • Material identity is required on active voxel state (material_id, material_profile_id, material_phase_id).
  • Runtime target bootstrap stamps default destructible target columns/wall during setup (WorldSimulation calls simulation_controller.stamp_default_voxel_target_wall(...) after configure_environment(...)).
  • Default fracture-prone column material profile is rock via canonical profile resolution (stone/gravel canonicalize to rock).
  • Transform execution is GPU-required; no CPU-success fallback path exists for unified transform runtime.
  • Legacy named stage requests (weather/hydrology/erosion/solar) are unsupported in active runtime and fail as unsupported_legacy_stage.

Rendering and GPU Shaders

  • Chunked terrain rendering via MultiMeshInstance3D for voxel blocks.
  • GPU flow and terrain shading sample generic transform field textures/buffers (no named stage authority).
  • GPU river-flow overlay shader driven by baked flow-map rows.
  • GPU cloud layers: animated cloud plane + volumetric cloud shell.
  • GPU post-processing effects are driven by transform diagnostics/material state instead of named weather-stage contracts.
  • Volumetric fog + automatic day/night sun animation, integrated with global lighting and SDFGI-enabled demo environment.

Integrated Demo and Controls

  • Single canonical scene: VoxelWorldDemo (project main scene).
  • Terrain controls include dimensions, sea level, surface base/range, noise frequency/octaves/lacunarity/gain, smoothing, and cave threshold.
  • Flow-map visualizer controls (show/hide, threshold, stride) with animated flow arrows.
  • Timelapse-style simulation controls (play/pause/fast-forward/rewind/fork) and state restore.
  • Live stats report generic transform metrics/diagnostics in demo HUD/status labels.
  • Integrated runtime stack in one scene: worldgen + unified transform runtime + settlement/culture/ecology controllers + debug overlays.

Runtime target setup hook/config points:

  • Hook point: addons/local_agents/scenes/simulation/controllers/WorldSimulation.gd (configure_environment then stamp_default_voxel_target_wall during ready/bootstrap).
  • Column mutation path: addons/local_agents/simulation/controller/SimulationVoxelTerrainMutator.gd (stamp_default_target_wall, _apply_column_surface_delta).
  • Canonical material profiles: addons/local_agents/configuration/parameters/simulation/MaterialProfileTableResource.gd (rock, soil, water, ice, metal, wood, unknown).

Profile resources (defaults + wiring):

  • TargetWallProfileResource (addons/local_agents/configuration/parameters/simulation/TargetWallProfileResource.gd)
    • wall_height_levels=6
    • column_extra_levels=4
    • column_span_interval=3
    • material_profile_key="rock"
    • destructible_tag="target_wall"
    • brittleness=1.0
  • FpsLauncherProfileResource (addons/local_agents/configuration/parameters/simulation/FpsLauncherProfileResource.gd)
    • launch_speed=60.0
    • launch_mass=0.2
    • projectile_radius=0.07
    • projectile_ttl_seconds=4.0
    • launch_energy_scale=1.0
  • Wiring
    • WorldSimulation (addons/local_agents/scenes/simulation/controllers/WorldSimulation.gd) exposes target_wall_profile_override and fps_launcher_profile_override; in _ready() it applies the target-wall override via simulation_controller.set_target_wall_profile(...) and stamps via stamp_default_voxel_target_wall(...).
    • WorldSimulation configures FpsLauncherController with configure(world_camera, self, fps_launcher_profile_override).
    • FpsLauncherController (addons/local_agents/scenes/simulation/controllers/world/FpsLauncherController.gd) maps the profile into live launcher values in _apply_profile_resource(...).

Run

godot --path . --editor

Project is configured to launch VoxelWorldDemo as the main scene.

Headless smoke boot:

godot --headless --no-window --path . addons/local_agents/scenes/simulation/PlantRabbitField.tscn --quit

World generation demo:

godot --path . addons/local_agents/scenes/demos/VoxelWorldDemo.tscn

Tests

Core harness:

godot --headless --no-window -s addons/local_agents/tests/run_all_tests.gd --skip-heavy

Fast local harness (reduced core set, skips runtime-heavy by default):

godot --headless --no-window -s addons/local_agents/tests/run_all_tests.gd --fast --skip-heavy

Bounded runtime-heavy harness (each heavy test runs in its own process with per-test timeout):

godot --headless --no-window -s addons/local_agents/tests/run_runtime_tests_bounded.gd

Run one test_*.gd module via the canonical helper (default timeout is 120 seconds):

scripts/run_single_test.sh test_native_voxel_op_contracts.gd
scripts/run_single_test.sh test_native_voxel_op_contracts.gd --timeout=180

Equivalent direct harness invocation (when needed):

godot --headless --no-window -s addons/local_agents/tests/run_single_test.gd -- --test=res://addons/local_agents/tests/test_native_voxel_op_contracts.gd --timeout=120

Banned direct invocation (do not run test modules as SceneTree scripts):

godot --headless --no-window -s addons/local_agents/tests/test_native_voxel_op_contracts.gd

This is enforced in automation via scripts/check_no_direct_refcounted_invocation.sh (invoked by scripts/check_max_file_length.sh).

CI timeout policy for deterministic replay/runtime shards:

  • Default shard budget: 120 seconds.
  • GPU/mobile-oriented shard budget: 180 seconds.

Optional explicit GPU/mobile run:

godot --headless --no-window -s addons/local_agents/tests/run_runtime_tests_bounded.gd -- --use-gpu --timeout-sec=180

Run a subset with --tests (comma-separated, full path or filename):

godot --headless --no-window -s addons/local_agents/tests/run_runtime_tests_bounded.gd -- --timeout-sec=120 --tests=test_simulation_villager_cognition.gd,test_agent_runtime_heavy.gd

Useful runtime test flags:

  • --workers=<N>: run bounded runtime tests in parallel processes.
  • --fast: select a reduced runtime-heavy subset.
  • --use-gpu --gpu-layers=<N>: opt into GPU layer offload for runtime tests.
  • --context-size=<N> --max-tokens=<N>: override runtime model load context and token limits in heavy tests.

CPU vs GPU voxel benchmark:

# CPU-only simulation pipeline timing
godot --headless --no-window -s addons/local_agents/tests/benchmark_voxel_pipeline.gd -- --mode=cpu --iterations=3 --ticks=96 --width=64 --height=64 --world-height=40

# GPU render-path timing (run with rendering, not headless)
godot --path . -s addons/local_agents/tests/benchmark_voxel_pipeline.gd -- --mode=gpu --iterations=3 --gpu-frames=120 --width=64 --height=64 --world-height=40

Notes:

  • Current terrain noise generation is CPU-side; GPU benchmark covers shader/render upload/update loops.
  • Compare cpu.mean_ms vs gpu.total.mean_ms and gpu.avg_frame.mean_ms from JSON output.

Targeted deterministic checks include:

  • addons/local_agents/tests/test_smell_field_system.gd
  • addons/local_agents/tests/test_wind_field_system.gd

Notes

  • Runtime is intentionally scene-first and resource-driven.
  • Prefer voxel-native simulation/collision/destruction as the default implementation path.
  • Use RigidBody3D only as a minimal, exception-based choice.
  • Required systems should fail fast rather than silently fallback.
  • ARCHITECTURE_PLAN.md tracks breaking changes and migration status.

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for local-agents

Similar Open Source Tools

For similar tasks

For similar jobs