API Reference

The functions and classes added to the MiniScript core are called Application Programming Interfaces, or APIs. These are the built-in functions and methods you can use in your own Farmtronics programs.

Global Methods

Function	Usage
bot	Module of bot-related methods (bots only; null on the Home Computer)
env	Environment options; see https://miniscript.org/wiki/Env
exit	Exit the current script, returning to the command line
farm	Reference to the Location that represents your farm
file	File-handling module; see https://miniscript.org/wiki/File
import libname	Import a library module; see https://miniscript.org/wiki/Import
input(prompt)	Get a string of input from the user (https://miniscript.org/wiki/Input)
key	Module related to keyboard input; see https://miniscript.org/wiki/Key
text	Reference to the TextDisplay

Location Class

The Location class represents one area of the map. Each time you walk off the edge of the map (or through a door), the screen briefly goes dark, and then you appear in another part of the map, you have changed to a different location. Your farm is a Location, accessible via the global reference farm. You can also get a bot's location using bot.here (or bot.position.area).

Once you have a reference to a Location, you may use the following properties and methods.

Property/Method	Meaning
width	number of columns of tiles
height	number of rows of tiles
tile(column, row)	a map of information about the given tile, or null

The tile information will be null for empty, unimproved ground. For anything else you will get at least:

Key	Value Type	Value
type	string	base feature type

For trees, you will also get:

Key	Value Type	Value
treeType	integer	type of tree
growthStage	integer	tree's current stage of growth
health	integer	tree health
stump	boolean	whether this tree has been cut down
tapped	boolean	whether this tree has been tapped
hasSeed	boolean	whether this tree has seeds available

When the base type is "HoeDirt", then you will get:

Key	Value Type	Value
dry	boolean	whether this dirt is dry (true) or watered (false)
crop	map	map of information about the crop growing here, or null if none

The crop information provided is:

Key	Value Type	Value
name	string	name of the crop being grown, e.g. "Potato"
phase	integer	current growth phase of this crop
maxPhase	integer	number of growth phases of this crop type
mature	boolean	whether crop is fully grown (Note 1)
dead	boolean	whether the crop is dead
harvestable	boolean	whether this crop is ready to harvest
harvestMethod	integer	0 = normal (hand), 1 = scythe

Note 1: The mature flag does not seem to be used by the game on ordinary crops. Use harvestable if you want to know when a crop is ready.

Example: this script, on a bot, will print information about the crop ahead of it.

if not bot.ahead then
  print "Nothing ahead."
else if not bot.ahead.crop then
  print "I see " + bot.ahead.type + " ahead, but no crop."
else
  print "Growing: " + bot.ahead.crop.name
  print "Growth phase: " + bot.ahead.crop.phase + "/" + bot.ahead.crop.maxPhase
  if bot.ahead.crop.harvestable then
    print "Ready to harvest with method " + bot.ahead.crop.harvestMethod
  end if
end if

Bot Module

The following properties may be both read (to get the current status of the bot) and written (to change the bot's state):

Name	Type	Meaning
currentToolIndex	integer	index of the inventory item the bot is holding: 0 for the first item, 1 for the second, etc.
statusColor	color string	color of the status light, e.g. "#FFFF00" for yellow

These properties may be read, but not overwritten:

Name	Type	Meaning
position	map	current tile position: x, y, and area (a Location)
facing	integer	direction bot is facing: 0=north, 1=east, 2=south, 3=west
energy	integer	how much power the bot has left (0-270)
inventory	list	what item is in each slot of the bot's inventory
here	Location	shortcut for bot.position.area
ahead	map	tile information for the spot directly in front of the robot

Finally, the bot module contains these methods:

Name	Effect
forward	moves bot forward 1 tile
left	turns bot 90° to the left
right	turns bot 90° to the right
select toolNameOrIndex	sets currentToolIndex to the corresponding item
placeItem	place the selected item down ahead of the robot
harvest	harvest the crop in front of the robot (returns true on success)
useTool	applies current tool/item to the tile ahead of the robot
clearAhead	select and apply appropriate tool to clear tile ahead of the robot (Note 2)
clearAndMove distance=1	clear and move forward a given number of tiles (Note 2)

Note 2: Both clearAhead and clearAndMove are defined in /sys/startup.ms, and return 1 (true) if successful, or 0 (false) in case of failure (because the bot is facing some obstacle it can't clear).