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
me	Module of methods/data related to the Machine Environment
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
world	Returns information about the current state of the world

In addition to the above global methods (which should be read but not written), there is a special global variable which may be assigned to:

Variable	Default Value	Meaning
screenColor	"#333399"	color of screen background

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 me.here (or me.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
passable	integer	true (1) if a bot could pass through this tile; false (0) if it's impassable

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

For chests and bots, you will also get:

Key	Value Type	Value
inventory	list	list of items contained in this chest/bot

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 me.ahead then
  print "Nothing ahead."
else if not me.ahead.crop then
  print "I see " + me.ahead.type + " ahead, but no crop."
else
  print "Growing: " + me.ahead.crop.name
  print "Growth phase: " + me.ahead.crop.phase + "/" + me.ahead.crop.maxPhase
  if me.ahead.crop.harvestable then
    print "Ready to harvest with method " + me.ahead.crop.harvestMethod
  end if
end if

Me Module

The global function me returns a reference to the Machine Environment module. These provide access to data and functions that affect only the machine (robot or home computer) that the code is running on. Note that many of these really only apply to bots, and will do nothing useful on the home computer.

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

Name	Type	Meaning
name	string	machine name, used to distinguish it from others in code, chat, etc.
screenColor	color string	background color of the screen
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 bot status light, e.g. "#FFFF00" for yellow

These properties may be read, but not overwritten:

Name	Type	Meaning
isBot	integer	true (1) if this machine is a bot; false (0) if it's the home computer
owner	string	name of the player who owns this bot or computer
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 me.position.area
ahead	map	tile information for the spot directly in front of the robot

Finally, the me 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
takeItem n	take an item from slot n of the chest/bot ahead
swapItem idx1, idx2	swap the inventory items in slots idx1 and idx2
harvest	harvest the crop/product in front of the bot (returns true on success)
useTool	applies current tool/item to the tile ahead of the bot
clearAhead	select and apply appropriate tool to clear tile ahead of the bot (Note 2)
clearAndMove distance=1	clear and move forward a given number of tiles (Note 2)
collect	start collecting debris; use me.collect false to turn collection off

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).

World Module

The following properties of world may be read, but not overwritten:

Name	Type	Meaning
timeOfDay	integer	current in-game time, from 0600 (6 AM) to 2400 (midnight)
daySinceGameStart	integer	day number since start of game (value 1 means day 1, year 1)
dayOfSeason	integer	the current day in the in-game season, from 1 to 28
dayOfWeek	integer	current day of the week: 0 = Sunday, 6 = Saturday
dayOfWeekName	string	name of the current in-game day, e.g. "Tuesday"
year	integer	the current in-game year, starting at 1
season	integer	the season number, from 0 (Spring) to 3 (Winter)
seasonName	string	name of the current season
weather	string	current weather: sunny, stormy, raining, snowing, or windy
luck	number	current daily luck value (a small positive or negative number)

In addition, the world module contains these methods:

Name	Effect
chat message	adds the given message to the in-game chat, prefixed with the bot name or "Home Computer"
chatMessages	returns up to 10 most recent chat messages as a list of strings