Skip to Content
Overview

Last Updated: 4/7/2026

Agricultural Microworlds: Developer Overview

Agricultural Microworlds is a K-12 educational platform that teaches computer science fundamentals through agricultural simulations. Students use visual block-based programming (Blockly) to control farm equipment and complete lessons, while teachers create and assign curriculum tailored to different grade levels.

What Is Agricultural Microworlds?

Modern agriculture increasingly relies on autonomous technology—from GPS-guided tractors to precision planting systems. Yet students in agricultural programs often receive extensive training in biology and mechanics while missing exposure to the computer science skills needed to develop these technologies. Agricultural Microworlds bridges this gap by providing an accessible, agriculture-focused programming environment for K-12 students.

The platform operates similarly to Code.org or Scratch: students see a split interface with a Blockly programming workspace on the left and a live agricultural simulation on the right. As they snap together code blocks—move_forward(), toggle_harvesting(), wait_x_weeks(2)—the simulation responds in real time, showing a tractor moving across a field, crops growing based on accumulated growing degree days (GDD), and yield scores updating as students harvest.

Who Uses Agricultural Microworlds?

Teachers create lessons, set completion requirements, and assign them to classes. They can adjust difficulty by unlocking different block sets for different grade levels—K-5 students might see only basic movement blocks, while 9-12 students get access to sensors, conditionals, and custom block templates.

Students log in to see their assigned lessons, write block-based programs to control farm equipment, and complete objectives like “harvest the entire field without damaging crops” or “plant corn in rows with optimal spacing.”

The platform is designed to run on school computers with varying specs and internet capabilities, emphasizing efficiency and accessibility (including screen reader support, colorblind-friendly visuals, and low-dexterity controls).

Current Architecture

Agricultural Microworlds uses a dual architecture:

Frontend: React + Vite + Blockly

The simulation engine runs entirely client-side in JavaScript. The frontend is built with:

  • React 19 for UI components
  • Vite 7 as the build tool and dev server
  • Blockly 12.3.1 for the visual programming interface

All simulation logic lives in agricultural-microworlds.client/src/:

  • SimulationEngine/ orchestrates the game loop and executes student code via Web Workers
  • Simulation/SimManagers/ contains domain-specific managers (WeatherSimManager, CropSimManager, TractorSimManager)
  • States/ manages immutable simulation state (field tiles, tractor position, weather data)
  • SetUpCustomBlocks/ defines all custom Blockly blocks and code generation
  • Rendering/ handles the visual display of the simulation
  • Components/ provides React UI components (Blockly workspace, simulation canvas, controls)

Backend: ASP.NET Core

The backend (Agricultural-Microworlds.Server/) is currently minimal. Only a stub WeatherForecast controller exists. The specification document lists authentication, student/teacher dashboards, lesson storage, and database integration as “Not Started.”

The devcontainer includes a PostgreSQL 17 database service, but schema and integration are not yet implemented.

What’s Built vs. What’s Planned

✅ Finished (In Development)

  • Blockly workspace: Students can drag blocks from the library into the coding playground
  • Simulation rendering: Top-down view of a tractor on a field with crop/dirt/seedling tiles
  • Core simulation loop: Running student code updates the simulation in real time
  • Tractor movement: move_forward(), turn_left(), turn_right(), turn_x_degrees()
  • Farm operations: toggle_harvesting(), toggle_seeding(), switch_crop_being_planted(), change_vehicle()
  • Crop system: Planting seeds, growing crops based on GDD, harvesting for yield score
  • Weather simulation: GDD accumulation, rainfall, speed multiplier, K-State Mesonet data integration
  • Time control: wait_x_weeks() advances the simulation
  • Sensors: is_over_tile(), get_current_week(), custom_compare()
  • State management: Immutable state commits prevent SimManagers from interfering with each other
  • Stop/reset controls: Students can stop and reset the simulation

❌ Not Started

  • Authentication: Login, 2FA, password reset
  • Student dashboards: Lesson progress tracking, point averages, “cash earned” metrics
  • Teacher portal: Class management, lesson assignment, student progress reports
  • Lesson designer: Visual tool for creating custom lessons
  • Lesson completion: Automatic detection of completion conditions, end-of-lesson quizzes
  • Database integration: Storing users, lessons, progress, grades
  • Block unlocking: Grade-level-appropriate block sets
  • Custom block templates: Saving and reusing block sequences
  • Layout customization: Resizable panels in the microworld interface

The specification document’s feature status table shows the microworld simulation is “In Development” while all dashboard, authentication, and lesson management features remain “Not Started.”

Development Environment

Agricultural Microworlds uses GitHub Codespaces with a devcontainer as the primary development environment. The devcontainer provisions:

  • A Linux universal base image
  • .NET SDK for the ASP.NET Core backend
  • Node.js for the React frontend
  • PostgreSQL 17 database
  • VS Code extensions: C# tools, ESLint, Prettier

Developers open a Codespace, navigate to agricultural-microworlds.client/, run npm install && npm run build && npm run dev, and access the app via forwarded HTTPS ports (5000/5001).

Semester Goals

The current development roadmap (Sprints 5-7, Jan-Mar) focuses on:

  • Achieving 90%+ test code coverage
  • Improving inline documentation and wiki content
  • Updating soil and weather simulations
  • Implementing harvest collection management
  • Adding support for multiple crop types with different growth requirements
  • Automating collection processes

The backlog includes student/teacher dashboards, the lesson planner, education software integration, and full database setup.

Repository Structure

Agricultural-Microworlds.Server/     # ASP.NET Core backend (minimal)
  Controllers/WeatherForecastController.cs
  Program.cs
agricultural-microworlds.client/     # React frontend (main codebase)
  src/
    SimulationEngine/                # Game loop, Web Worker execution
    Simulation/SimManagers/          # Weather, crop, tractor logic
    States/                          # Immutable state management
    SetUpCustomBlocks/               # Blockly block definitions
    Rendering/                       # Simulation canvas rendering
    Components/                      # React UI components
  package.json                       # npm scripts: dev, build, test
.devcontainer/                       # Codespaces configuration
  devcontainer.json
  docker-compose.yml                 # app + postgres services
SpecificationDocument.md             # Feature requirements and status
README.md                            # Setup instructions

Next Steps for New Developers

If you’re new to the project, start by:

  1. Reading the installation and setup guide to get the app running locally
  2. Exploring the simulation engine architecture to understand the game loop and Web Worker pattern
  3. Reviewing the state management system to see how SimManagers coordinate without conflicts
  4. Examining the Blockly blocks reference to understand what students can program

The codebase is well-structured for contribution: each SimManager is independent, state classes are isolated, and Blockly block definitions are declarative. The specification document provides clear feature status, making it easy to identify areas needing development.

Installation Setup