# Fieldcraft: program a growing world

Fieldcraft is an independent Python learning adaptation inside the Higher Python course. It uses original artwork and teaching text. This document is a readable source pack: download it and upload the Markdown file to NotebookLM to study the concepts and ask questions about the API.

## How to learn

Predict what your program will do before running it. Change one variable at a time. Observe the coordinates, resources and console, then explain the result in your own words. Pause or single-step when a result surprises you.

The field is a square grid. Coordinate (0, 0) is at the bottom left. North increases y; East increases x. Ordinary farm travel wraps around the field; maze walls and trail mode introduce movement restrictions. Simulation ticks track actions and growth. Animation speed changes how quickly you watch the simulation.

## First experiment: variables

```python
steps = 3
for step in range(steps):
    move(East)
print(get_pos_x(), get_pos_y())
```

Predict the final x coordinate. Change `steps` to 2, then to the world size. Why does the result change at the edge?

## Loops and conditions

```python
size = get_world_size()
for column in range(size):
    for row in range(size):
        if can_harvest():
            harvest()
        move(North)
    move(East)
```

The inner loop visits a column. The outer loop repeats this for every column. `can_harvest()` is a Boolean test that prevents collecting an immature crop.

An ongoing automation program may use `while True`. Pause and Stop remain available. Start with a small experiment so you understand how the loop changes the field.

## Functions and collections

Put repeated instructions inside a function and call it when needed. Lists, dictionaries and sets let you remember measurements and visited coordinates. For maze exploration, store each coordinate you have visited and avoid revisiting it unnecessarily. Use `can_move(direction)` to inspect walls before moving.

## Farming toolkit

| Function | Purpose |
| --- | --- |
| `move(direction)` | Move one tile and report whether movement succeeds. |
| `can_move(direction)` | Check whether the route is open. |
| `can_harvest()` | Check whether the current crop can be collected. |
| `harvest()` | Collect the current crop or special challenge object. |
| `plant(entity)` | Plant a crop if its ground and resource requirements are met. |
| `till()` | Switch between Grassland and Soil. |
| `measure(direction)` | Inspect a crop's value, or challenge information. The direction is optional. |
| `swap(direction)` | Exchange adjacent crops. |
| `get_pos_x()`, `get_pos_y()` | Get the drone's coordinates. |
| `get_world_size()` | Get the width and height of the square field. |
| `get_entity_type()` | Inspect the crop under the drone. |
| `get_ground_type()` | Inspect the ground under the drone. |
| `get_water()` | Inspect the current tile's water. |
| `get_tick_count()` | Read elapsed simulation ticks. |
| `num_items(item)` | Read a resource counter. |
| `get_cost(entity)` | Inspect planting costs. |
| `use_item(item, amount)` | Use a farming item; amount is optional. |
| `change_hat(hat)` | Change between the normal and trail challenge modes. |
| `get_companion()` | Inspect a companion planting request. |
| `wait(ticks)` | Let simulation time advance. |
| `clear()` | Clear the farm. This changes your current field. |
| `spawn_drone(function, *args)` | Start an unlocked additional drone running a function. |
| `print(...)` | Write values to the bounded console. |

Constants use these namespaces: `Entities.Grass`, `Entities.Bush`, `Entities.Tree`, `Entities.Carrot`, `Entities.Sunflower`, `Entities.Pumpkin`, `Entities.Cactus`; `Grounds.Grassland`, `Grounds.Soil`; `Hats.Default`, `Hats.Dinosaur`; and directions `North`, `South`, `East`, `West`.

Resources include `Items.Hay`, `Items.Wood`, `Items.Carrot`, `Items.Pumpkin`, `Items.Power`, `Items.Water`, `Items.Fertiliser`, `Items.Weird_Substance`, `Items.Gold`, `Items.Cactus`, `Items.Bones`. The runtime's resource bar and upgrade descriptions show the available names and costs for your world.

## Experiments across worlds

- Growing field: gather resources, then buy an upgrade. Generalise a traversal using `get_world_size()`.
- In the growing field, grow Carrots: check the ground, cultivate Soil, plant a Carrot, wait for growth and collect it.
- Sunflowers: keep a running maximum of the measured values. Explain why collecting the first plant you see may be inefficient.
- Pumpkins: identify dead crops and replant missing cells. Separate sensing from action.
- Cactus: use comparisons and adjacent swaps to organise numeric values. Observe how sorted groups change the harvest.
- Maze: model locations as a graph. Use a visited collection and functions to navigate safely.
- Trail: plan a route that avoids the growing tail. Predict which cells remain reachable.

These are learning prompts rather than a scored examination. Preset worlds provide focused practice alongside continuous resource progression.

## Editor and debugging

Run starts the current file. Pause freezes execution. Resume continues a paused run. Step executes a small part of the program so you can observe the active line and variables. Stop ends the program while keeping the current field.

The game interpreter supports a restricted Python subset: assignments, arithmetic, comparisons, conditions, loops, user functions and collections. It does not grant host imports, filesystem access or network access. Use the separate Python course terminal for general Python exercises.

Keep helper routines in additional editor files. The workspace supports up to 20 files, each at most 20 KB, with a total code size of 200 KB. An example replaces the current file only after confirmation and keeps a recovery copy.

## Save your work

Code and progress autosave are independent controls. Worlds keep separate progress while sharing your code files. Reset deliberately creates a new current world using your seed and keeps a recovery copy. Download a versioned JSON save to keep an independent backup or move browsers. Imports validate every world before replacing your workspace. If validation fails, your original workspace stays available.

Restoring a save restores the field, resources and main drone in an idle state. Active program execution and extra drones are not restored; run your saved program to launch them again. Browser storage can be cleared by the browser or device, so keep a downloaded backup for work you want to preserve.

## Use AI thoughtfully

Ask for a hint or an explanation of a small code fragment. Tell the tool what you predicted and what happened. Trace suggested code yourself, check API names in this guide, and run a small experiment to check its assumptions. AI output can be mistaken even when it sounds confident. Never paste private information, and follow your teacher's rules about acknowledging assistance.

Example prompt: “I am learning nested loops. My 4×4 field traversal visits only one column. Give me one hint without writing the whole solution.”