Appearance
Writing code
Your program is the brain of your company. This page explains how a program is built. The full list of names is in the API reference.
You write in Python or in Go. The examples here are in Python. In Go the names are the same, in Go style: car.GoTo(place) for car.go_to(place).
How a program is laid out
- Your repository has one start file:
main.pyormain.go. - You can put more files of your own next to it and import them.
- There is no settings file of the game. Everything else comes from the city.
- Your program may use the standard library of its language and the game's own library, and nothing else. It runs in a closed box with no network.
The idea: events in, commands out
Your program does not run in a loop and ask "is there something to do?". The game tells it when something happens. That is an event. Your program answers with commands.
python
from delivery import on, me
@on.idle
def next_job(event):
car = me.cars[event.car]
... # look around, then send one command to this carA function that handles an event is called a handler. The game calls your handlers one after the other, never two at once. So you never need locks, and nothing changes under your hands in the middle of a handler.
A slow handler holds up the events behind it. The city does not wait for you, so slow code simply reacts late.
Events
The most important event is idle: one of your cars is free and waits for a command. Most programs are built around it.
idle tells you which car, and why it is free: it has arrived, loaded, delivered, refuelled, and so on.
idle is repeated. While a car stays free, idle comes again every few ticks. So a program that missed an event, or crashed once, gets another chance.
Some other events you will use early:
| Event | When it comes |
|---|---|
orders_changed | New orders appeared, or orders were taken or ran out. |
fuel_below(x) | A car's fuel dropped below the limit x that you chose. |
service_below(x) | The same for the service level. |
car_broke_down | A car ran out of fuel or service, and the fine was charged. |
command_failed | A command that was accepted could not be done after all. |
day_ended | A day is over. |
started | Your program just started. |
You choose the limit of fuel_below yourself:
python
@on.fuel_below(20)
def find_fuel(event):
...Commands
A command changes the city. These are the commands for a car in stage 1:
| Command | What it does |
|---|---|
car.go_to(place) | Drive to a place by the shortest route. |
car.load(order) | At a storage: load the goods of this order that the storage has. The first load takes the order. |
car.deliver(order) | At the order's shop, with all goods on board: hand them over and get the delivery fee. |
car.refuel() | At a fuel station: fill the tank. With an amount, car.refuel(20), it adds only that much. |
car.service() | At a service station: restore the service level. |
car.halt() | Stop driving and stand at the next place. |
A command and its answer
Every command is answered at once: accepted, or refused with a short code that says why.
python
answer = car.load(order)
if answer.refused:
log(f"could not load: {answer.code}") # for example "too_heavy"An accepted command takes effect at the next tick. It can still fail there. The usual case: two cars load the same order in one tick, the first one takes it, and the second one's command fails. Then your program gets the event command_failed, with the same kind of code.
So "accepted" means "this looked fine when you asked". It does not mean "done".
Give a reason
Every command can carry a reason:
python
car.go_to(shop.place, reason=f"order {order.id} pays {order.fee}")The reason changes nothing in the game. It is for you. It shows up in the history of decisions, where it turns "car 2 drove to Baker 12" into "car 2 drove to Baker 12 because that order pays 31". The game also notes the file and the line that sent the command.
Reading the city
Your program can read the city at any time. The game's library keeps a copy of everything you are allowed to see, so reading is fast.
There are two kinds of data.
Public data is the same for every company:
| Name | What it holds |
|---|---|
city | The tick, the day, the settings. |
city.map | Roads, places, districts. |
businesses | Every business: kind, place, prices, stock. |
orders | Every open order: shop, goods, delivery fee, when it runs out, whether it can be taken yet, and whether a car has taken it. |
cars | Every car in the city: its company and where it is. |
companies | Every company: name, colour, place in the ranking, wealth. |
Private data is yours alone:
| Name | What it holds |
|---|---|
me | Your cash, held money, loan, wealth, licenses. |
me.cars | Your cars in full: fuel, service level, cargo, taken orders, driver. |
me.drivers | Your drivers: salary, multipliers, whether they are leaving. |
memory | Your program's memory, see below. |
Nobody can read another company's private data, by any way.
Questions the game answers for you
Some questions need the rules of the game, such as finding a route. Your program asks the game:
python
far = city.route_length(car.place, shop.place) # the length of the shortest route
station = city.nearest(car.place, kind="fuel_station")The memory
An ordinary variable in your program is lost every time your program restarts. And it restarts often: on every push, after a crash, when you ask for it, and when the game gets a new version.
For anything that must last, use the memory. The game keeps it for you.
python
from delivery import memory
memory["plan"] = "grow the fleet"
plan = memory.get("plan", "deliver")- It survives every restart.
- Your program, the CLI and an AI assistant all read and write the same memory. So an assistant can leave a note for your program, and your program can leave one for the assistant.
- It belongs to one company in one city. It is deleted when you leave that city, or when you reset it.
Using an ordinary variable for something that must last is the most common first mistake.
Notes from your program
log("text") writes a line into your company's log. Whatever your program prints goes into the same log. You read it in the Log panel of the city page, or with the CLI.
When a handler fails
An error in a handler does not stop your program. The error is recorded with its file and line, and the next event is handled as usual. See When something goes wrong.
Actions: talking to your running code
This comes in stage 5.
Your program can offer actions: named functions that you, or an assistant, can call while the program runs.
python
from delivery import action, memory
@action(text="The most this company bids for a car", lowest=0, highest=20000)
def set_highest_bid(amount: int):
memory["highest_bid"] = amount
return f"highest bid is now {amount}"The game builds a control panel from your actions, with a field for each value and a button. The CLI and MCP can call the same actions. What your function returns is the answer the caller sees.
A value can be a number, a text, a yes or no, or a choice from a list.
Your program can also show values on the panel:
python
publish("orders delivered today", 14)A program outside the game
You do not have to upload your program. You can run it on your own machine and let it control your company from there. It can do everything an uploaded program can do, with one difference: it is not sent events. It has to ask what changed.
python
from delivery import outside
city = outside.connect("riverton") # uses your stored access key
tick = city.memory.get("last_tick", 0)
while True:
changed = city.changes(since=tick) # waits a moment when nothing changed
for event in changed.events:
if event.name == "idle":
car = city.me.cars[event.car]
... # decide, then for example:
car.go_to(place, reason="...")
tick = changed.tick
city.memory["last_tick"] = tickAn uploaded program sits next to the game and answers faster than a program far away. If speed matters, upload.
Trying it on your own machine
You can run your program in a city on your own machine before you push it. There the city waits for your program, so you can stop it on any line. See The CLI.