Last Updated: 4/6/2026

Blockly Blocks Reference

This is a complete reference for all programming blocks available in Agricultural Microworlds. Students use these blocks to control farm equipment, manage crops, and complete lessons.

Block Categories

Blocks are organized into seven categories in the toolbox:

1. Movement: Control vehicle position and orientation
2. Variables: Store and retrieve values
3. Numbers: Numeric constants and random values
4. Control: Farm operations and time control
5. Logic: Conditionals and comparisons
6. Loops: Repetition structures
7. Events: Program entry points

Movement Blocks

move_forward

Visual: move forward for [1] seconds

Parameters:

• DURATION (Number): How many seconds to move forward

Behavior: Moves the active vehicle forward in the direction it’s facing for the specified duration. The vehicle travels at 20 pixels/second (configured in ImplementState.basespeed).

Generated code: await simulationMethods.moveForward(duration);

Example:

move forward for [5] seconds
→ Vehicle moves 100 pixels forward (5 seconds × 20 px/s)

turn_left

Visual: turn left

Parameters: None

Behavior: Rotates the active vehicle 90 degrees counterclockwise. The turn happens over time at 90 degrees/second (configured in ImplementState.turnSpeed), taking approximately 1 second to complete.

Generated code: await simulationMethods.turnXDegrees(-90);

turn_right

Visual: turn right

Parameters: None

Behavior: Rotates the active vehicle 90 degrees clockwise at 90 degrees/second.

Generated code: await simulationMethods.turnXDegrees(90);

turn_x_degrees

Visual: Turn [90] degrees [left/right]

Parameters:

• DEGREES (Number): Amount to turn
• DIRECTION (Dropdown): “left” (0) or “right” (1)

Behavior: Rotates the active vehicle by the specified angle. Left turns use negative degrees, right turns use positive degrees. The turn rate is 90 degrees/second.

Generated code:

// Left: await simulationMethods.turnXDegrees(-1 * degrees);
// Right: await simulationMethods.turnXDegrees(degrees);

Example:

Turn [45] degrees [left]
→ Vehicle rotates 45° counterclockwise over 0.5 seconds

Control Blocks

toggle_harvesting

Visual: turn harvesting [ON/OFF]

Parameters:

• toggleType (Dropdown): “ON” (1) or “OFF” (0)

Behavior: Enables or disables the harvester header. When ON and the harvester drives over mature crops, it collects them and adds to the yield score. Driving over growing crops with the header ON damages them (resets to unplanted, no score). Only works when the active vehicle is the harvester.

Generated code: simulationMethods.toggleHarvesting(true/false);

Yield scores:

• Wheat: 1 point
• Soybean: 2 points
• Corn: 3 points

toggle_seeding

Visual: turn seeding [ON/OFF]

Parameters:

• toggleType (Dropdown): “ON” (1) or “OFF” (0)

Behavior: Enables or disables the seeder. When ON and the seeder drives over unplanted tiles, it plants the selected crop type (see switch_crop_being_planted). Only works when the active vehicle is the seeder.

Generated code: simulationMethods.toggleSeeding(true/false);

wait_x_weeks

Visual: wait [2] weeks

Parameters:

• WEEKS (Number): Number of weeks to wait

Behavior: Pauses vehicle movement and advances simulation time by the specified number of weeks. During the wait, the simulation runs 6× faster (configured in WeatherState.getSpeedMultiplier()). This allows crops to grow without requiring the vehicle to move.

Time calculation: 1 week = 7 days × 24 hours = 168 simulated hours

Generated code: await simulationMethods.waitXWeeks(weeks);

Example:

wait [8] weeks
→ Simulation advances 56 days, crops accumulate ~8 weeks of GDD

switch_crop_being_planted

Visual: Switch crop being planted to [Wheat/Corn/Soybean]

Parameters:

• toggleType (Dropdown): “Wheat” (0), “Corn” (1), or “Soybean” (2)

Behavior: Changes which crop the seeder plants when seeding is ON. Each crop has different GDD requirements to reach maturity.

Generated code: simulationMethods.switchCropBeingPlanted(CROP_TYPES.WHEAT/CORN/SOY);

Crop types and GDD requirements:

change_vehicle

Visual: Swaps the vehicle to [Harvester/Seeder]

Parameters:

• toggleVehicle (Dropdown): “Harvester” (0) or “Seeder” (1)

Behavior: Switches which vehicle the student’s code controls. The harvester starts at y-50, the seeder at y+50 (both off-screen at x=-150). Switching vehicles changes which one receives movement commands and which one the camera follows.

Generated code: simulationMethods.setMainVehicleType(VEHICLES.HARVESTER/SEEDER);

Vehicle types:

Sensor/Logic Blocks

is_over_tile

Visual: is over [Unplanted/Seeded/Grown] tile

Parameters:

• TYPE (Dropdown): “Unplanted” (0), “Seeded” (1), or “Grown” (2)

Returns: Boolean (true if any tile under the vehicle’s header matches the type)

Behavior: Checks if the vehicle is currently over a tile with the specified crop stage. Samples 10 points across the header width (64 pixels) at the header offset (20 pixels in front of the vehicle center).

Generated code: simulationMethods.CheckIfPlantInFront(type)

Crop stages:

Example:

if [is over [Grown] tile]
  turn harvesting [ON]
  move forward for [1] seconds
  turn harvesting [OFF]

custom_compare

Visual: [5] = [5]

Parameters:

• A (Number): Left operand
• B (Number): Right operand

Returns: Boolean (true if A equals B)

Behavior: Compares two numbers for equality. This is a simplified comparison block—standard Blockly comparison blocks (<, >, ≤, ≥, ≠) are not included in the current toolbox.

Generated code: A == B

Example:

if [[get_current_week] = [8]]
  wait [1] weeks

get_current_week

Visual: Current Week

Parameters: None

Returns: Number (current week number, starting from 0)

Behavior: Returns the current simulation week. Calculated as floor(currentDayIndex / 7).

Generated code: simulationMethods.currentWeek

Example:

repeat until [[Current Week] = [12]]
  wait [1] weeks
→ Waits until week 12

Number Blocks

math_number

Visual: [1]

Parameters:

• NUM (Number field): Any numeric value

Returns: Number

Behavior: A constant numeric value. Used as input to other blocks.

Generated code: number

math_random_int

Visual: random integer from [1] to [10] (standard Blockly block)

Parameters:

• FROM (Number): Minimum value (inclusive)
• TO (Number): Maximum value (inclusive)

Returns: Number (random integer in range)

Behavior: Generates a random integer between FROM and TO. Useful for randomized lesson objectives.

Variable Blocks

variables_get

Visual: [variableName] (standard Blockly block)

Parameters:

• Variable name (selected from dropdown)

Returns: The variable’s current value

Behavior: Retrieves the value of a user-created variable.

variables_set

Visual: set [variableName] to [0] (standard Blockly block)

Parameters:

• Variable name (selected from dropdown)
• Value (any type)

Behavior: Assigns a value to a user-created variable.

Example:

set [harvestedRows] to [0]
repeat [10] times
  move forward for [5] seconds
  turn right
  set [harvestedRows] to [[harvestedRows] + [1]]

Create variable button

Visual: Create variable... (button in Variables category)

Behavior: Opens a dialog to create a new variable. Variables persist for the duration of the program run.

Logic Blocks

controls_if

Visual: if [condition] do [blocks] (standard Blockly block)

Parameters:

• Condition (Boolean)
• Statement blocks

Behavior: Executes the nested blocks only if the condition is true. Can be extended with “else if” and “else” branches using the gear icon.

logic_boolean

Visual: [true/false] (standard Blockly block)

Parameters:

• Boolean value (dropdown)

Returns: Boolean

Behavior: A constant boolean value.

Loop Blocks

controls_repeat_ext

Visual: repeat [10] times do [blocks] (standard Blockly block)

Parameters:

• Count (Number): Number of iterations

Behavior: Executes the nested blocks the specified number of times.

Example:

repeat [4] times
  move forward for [5] seconds
  turn right
→ Drives in a square

controls_whileUntil

Visual: repeat while/until [condition] do [blocks] (standard Blockly block)

Parameters:

• Mode (Dropdown): “while” or “until”
• Condition (Boolean)

Behavior: Repeats the nested blocks while the condition is true (while mode) or until it becomes true (until mode).

Example:

repeat until [is over [Grown] tile]
  move forward for [1] seconds
→ Moves until finding a mature crop

Event Blocks

start_program

Visual: On Begin

Parameters: None

Behavior: Marks the entry point for the student’s program. This block should be at the top of the workspace. Currently generates no code (empty newline), but serves as a visual indicator of program start.

Generated code: \n

Block Styles and Colors

Blocks are color-coded by category:

Code Generation

When students click “Run”, Blockly generates JavaScript code using the javascriptGenerator. The generated code:

1. Is asynchronous: Uses await for movement, turns, and waits
2. Calls simulation methods: All commands route through simulationMethods object
3. Runs in a Web Worker: Executes in a separate thread to prevent UI blocking
4. Communicates via messages: Worker posts commands to the main thread, which executes them in the simulation engine

Example workspace:

On Begin
  turn harvesting [ON]
  repeat [10] times
    move forward for [5] seconds
    turn right

Generated JavaScript:

await simulationMethods.moveForward(5);
await simulationMethods.turnXDegrees(90);
await simulationMethods.moveForward(5);
await simulationMethods.turnXDegrees(90);
// ... (repeats 10 times)

Enum Reference

CROP_TYPES

Defined in src/States/StateClasses/CropState.js:

export const CROP_TYPES = {
  EMPTY: 0,   // No crop
  WHEAT: 1,   // 1000 GDD, yield score 1
  CORN: 2,    // 1300 GDD, yield score 3
  SOY: 3      // 900 GDD, yield score 2
};

CROP_STAGES

export const CROP_STAGES = {
  UNPLANTED: 0,  // Bare dirt
  SEEDED: 1,     // Planted, growing
  MATURE: 2      // Ready to harvest
};

VEHICLES

Defined in src/States/StateClasses/ImplementState.js:

export const VEHICLES = {
  HARVESTER: 0,  // Collects mature crops
  SEEDER: 1      // Plants seeds
};

Common Patterns

Harvest a field

On Begin
  change_vehicle to [Harvester]
  turn harvesting [ON]
  repeat [20] times
    move forward for [10] seconds
    turn right
    move forward for [2] seconds
    turn right
  turn harvesting [OFF]

Plant and wait for growth

On Begin
  change_vehicle to [Seeder]
  switch_crop_being_planted to [Corn]
  turn seeding [ON]
  move forward for [10] seconds
  turn seeding [OFF]
  wait [10] weeks
  change_vehicle to [Harvester]
  turn harvesting [ON]
  move forward for [10] seconds

Conditional harvesting

On Begin
  change_vehicle to [Harvester]
  repeat [100] times
    if [is over [Grown] tile]
      turn harvesting [ON]
      move forward for [1] seconds
      turn harvesting [OFF]
    else
      move forward for [1] seconds

Block Unlocking (Planned)

The specification document mentions grade-level block unlocking (currently “Not Started”):

• K-5: Only basic movement and control blocks
• 6-8: Add variables and simple logic
• 9-12: Full block set including custom templates

This feature is not yet implemented—all blocks are currently available to all users.

File Locations

• Block definitions: src/SetUpCustomBlocks/customBlockDefinitions.js
• Code generators: src/SetUpCustomBlocks/blocklyJSGenerator.js
• Toolbox config: src/SetUpCustomBlocks/toolboxConfig.js
• Crop enums: src/States/StateClasses/CropState.js
• Vehicle enums: src/States/StateClasses/ImplementState.js