Appearance
API reference
This page lists everything a program can be told, can do and can read. Writing code explains how the parts fit together.
The same list serves an uploaded program, the CLI, MCP and the VS Code extension.
Each entry names the stage in which it arrives. The stages are explained in The rules.
The names can still change
This is an alpha version. A name can still change when building shows that a better one is needed.
Events
Your uploaded program subscribes to an event with @on.<name>. The CLI and MCP get the same events in the answer to "what changed since tick N".
Most events come from the city itself. A few are made by the server around your program: started, action_called, the events with a limit the code chose (fuel_below, service_below, stock_below), and the idle that each free car gets when the code starts. To your program they all look the same.
The main event
| Event | Stage | Carries | Meaning |
|---|---|---|---|
idle | 1 | car, why | A car is free and waits for a command. This is the event most code is built around. |
why says what just happened: started (the car is new, or the code just started), arrived, loaded, delivered, refuelled, serviced, recovered (back after a break down), no_route, failed (the car's last command failed at the tick), still_idle.
idle is repeated. While a car stays free, idle is sent again every few ticks with still_idle. So code that missed an event, or crashed once, gets another chance.
Cars and drivers
| Event | Stage | Carries | Meaning |
|---|---|---|---|
fuel_below(x) | 1 | car, fuel | The car's fuel dropped below the limit x that the code chose. |
service_below(x) | 1 | car, service_level | The same for the service level. |
car_broke_down | 1 | car, cause, fine | The car ran out of fuel, or its service level reached zero. The fine was charged. |
driver_quitting | 2 | driver, car, ticks_left | A driver announced that they leave. |
driver_left | 2 | driver, car | The driver left. The car cannot move until another driver is assigned. |
Orders
| Event | Stage | Carries | Meaning |
|---|---|---|---|
orders_changed | 1 | added, taken, gone | The set of orders changed. One event covers all changes of a tick. |
taken_order_expired | 1 | order, car, penalty | An order that one of this company's cars had taken ran out of time. From stage 3 the penalty was charged. |
command_failed | 1 | command, code | A command that was accepted failed when the tick applied it, for example because another car took the order first. The code is one of the refusal codes. |
The full set of orders is always readable as orders. The event says what changed, so that code does not have to compare.
Markets and auctions
| Event | Stage | Carries | Meaning |
|---|---|---|---|
offer_added | 2 | market, offer | A new offer is on a market. |
offer_removed | 2 | market, offer | An offer left a market without being sold. |
bid_placed | 2 | offer, leading_bid, leader | Someone bid on an offer. Sent to everyone who can see the market. |
auction_closed | 2 | offer, winner, amount | An auction ended. A bidder who lost has their held money back. |
Money
| Event | Stage | Carries | Meaning |
|---|---|---|---|
payment | 1 | kind, amount, what it was for | Money came in or went out in one piece: a delivery fee, a fine, a purchase, a dividend. |
loan_changed | 1 | loan, limit, why | The company's loan changed: it took or repaid a loan, or the bank lent by itself. |
forced_sale | 2 | what was sold, for how much | The bank sold shares or cars of the company, because its loan stayed above its loan limit. |
Salaries are not announced one by one. They are charged every tick, and they show in the company's readable data.
Other companies
| Event | Stage | Carries | Meaning |
|---|---|---|---|
company_left | 3 | company | A company left the city. |
Businesses and the city
| Event | Stage | Carries | Meaning |
|---|---|---|---|
day_ended | 1 | day, a summary of the company's day | A day is over. Interest was charged. From stage 4 dividends and losses were settled too. |
shares_changed | 4 | business, who holds what | Shares of a business changed hands. |
control_changed | 4 | business, controller | A business has a new controller, or none. Sent to its shareholders. |
stock_below(x) | 4 | business, item, amount | Stock in a business this company controls dropped below the limit the code chose. |
city_grew | 4 | step, the new part of the map | The city grew by one step. |
The code itself
| Event | Stage | Carries | Meaning |
|---|---|---|---|
started | 1 | version, why | The code just started: first start, a new push, a restart, or after a crash. |
action_called | 5 | action, values, caller | Someone called an action the code declared. |
Commands
A command changes the city.
Every command can carry a reason, a short text for the history of decisions.
Every command gets an answer at once: accepted, or refused with a code that says why. An accepted command takes effect at the next tick. It can still fail there, for example when another car takes the order first. Then the company gets the event command_failed with the same kind of code. See Writing code.
Every command has an id. Every event that a command caused carries that id as cause.
Cars
| Command | Stage | Meaning |
|---|---|---|
car.go_to(place) | 1 | Drive to a place by the shortest route. |
car.load(order) | 1 | At a storage: load every item of the order that this storage has and the car still needs. The first load takes the order. |
car.deliver(order) | 1 | At the order's shop, with all its goods on board: hand them over and receive the delivery fee. |
car.refuel(amount) | 1 | At a fuel station: fill the tank, or add the given amount. |
car.service() | 1 | At a service station: restore the service level. |
car.halt() | 1 | Stop driving and stand at the next place. |
car.sell_to_city() | 2 | Sell the car to the city for its market value. The car must be empty and at a place. |
Drivers
| Command | Stage | Meaning |
|---|---|---|
driver.assign(car) | 2 | Assign the driver to a car. A driver already in that car becomes a spare driver. |
driver.unassign() | 2 | Take the driver out of their car. |
driver.dismiss() | 2 | Stop employing the driver. |
Licenses and markets
| Command | Stage | Meaning |
|---|---|---|
buy_license(kind, level) | 2 | Buy a fleet license level, or from stage 4 a business license. |
take_loan(amount) | 2 | Borrow from the bank, up to the loan limit. |
repay_loan(amount) | 2 | Pay back a part or all of the loan. |
bid(offer, amount) | 2 | Place a bid, or raise your own. |
cancel_bid(offer) | 2 | Take your bid back. |
Shares
| Command | Stage | Meaning |
|---|---|---|
offer_shares(business, count, starting_price) | 4 | Put a lot of your shares on the business market. |
withdraw_offer(offer) | 4 | Take your offer back, if nobody has bid on it. |
sell_shares_to_city(business, count) | 4 | Sell shares to the city for their market value. |
Running a business
Only the controller of the business may send these.
| Command | Stage | Meaning |
|---|---|---|
shop.set_retail_price(item, price) | 4 | Set what residents pay. |
shop.post_order(items, fee, price_limits, expiry) | 4 | Post an order. |
shop.set_stock_list(items) | 4 | Choose which items the shop stocks. |
storage.set_wholesale_price(item, price) | 4 | Set what shops pay. |
storage.set_stock_plan(item, amount) | 4 | Choose how much of an item the storage brings in. |
fuel_station.set_price(price) | 4 | Set the fuel price. |
service_station.set_price(price) | 4 | Set the service price. |
business.upgrade() | 4 | Pay for the next business level. |
business.use_built_in(setting) | 4 | Hand one setting back to the built-in rules. |
Operations
An operation does not change the city. It reads, or it concerns your program and its memory.
The code's own interface
| Operation | Stage | Meaning |
|---|---|---|
declare_action(name, parameters, text) | 5 | Tell the game about an action that others may call. |
answer(call, value) | 5 | Send an answer to whoever called an action. |
publish(name, value) | 5 | Show a value on the control panel. |
Memory and notes
| Operation | Stage | Meaning |
|---|---|---|
memory[name] = value, memory[name], del memory[name] | 1 | Write, read and remove a value in the company's memory. |
log(text) | 1 | Write a line into the company's log. |
city.route_length(a, b) | 1 | The length of the shortest route between two places. The game answers it, with its own route finding. |
city.nearest(place, kind) | 1 | The nearest business of a kind from a place, by route. The game answers it. |
Only from outside
These exist for the CLI, MCP and the VS Code extension, not for an uploaded program.
| Operation | Stage | Meaning |
|---|---|---|
changes(since) | 1 | Get the events and the changed data since a tick. |
restart_code() | 1 | Restart the company's uploaded code. |
code_status() | 1 | Which version runs, the state of the last push, and recent errors. |
call_action(name, values) | 5 | Call an action the uploaded code declared, and get its answer. |
decisions(filter) | 1 | Read the company's history of decisions. Each entry says when, who decided, what it reacted to, what was decided, the reason, the answer, what came of it, and the line of code. |
log_lines(since) | 1 | Read the company's log from a tick on. |
check_code(files) | 1 | Ask whether this code would be accepted, without pushing it. |
cities() | 1 | The player's cities, and the listed shared cities, each marked as a lobby or as running. Only a lobby can be joined. |
actions() | 5 | The actions the uploaded code declared. |
Helpers
A helper is a small function of the game's library. It only combines data your program can already read.
| Helper | Stage | Meaning |
|---|---|---|
car.free_capacity | 1 | The car's capacity minus its cargo. |
car.has_all(order) | 1 | Whether the car carries every item of the order. |
order.weight | 1 | The total weight of the order's items. |
order.next_storage(car) | 1 | Among the storages that hold an item the car still needs for this order, the nearest one by route. It uses city.nearest. |
Why a command is refused or fails
A command that is refused at once, and a command that fails at the tick, both carry one of these codes. The list grows with the stages.
| Code | Meaning |
|---|---|
not_yours | The car, driver or business does not belong to this company, or it does not control it. |
unknown | No such car, order, place or offer. |
no_driver | The car has no driver assigned. |
broken_down | The car has broken down and waits for its recovery. |
wrong_place | The car is not at the place this command needs. |
no_route | No road leads there. |
order_taken | Another car has taken this order. |
order_gone | The order expired or was delivered. |
too_heavy | The order does not fit into the car's free capacity. |
not_in_stock | The storage has none of the items the car still needs. |
over_price_limit | The storage's wholesale price is above the order's price limit. |
goods_missing | The car does not carry all goods of the order. |
no_cash | The company cannot pay for this. |
over_loan_limit | The company's loan is above its loan limit, so it cannot buy, bid or borrow more. |
license_needed | The company lacks the license this needs. This includes bidding on shares without the license for that kind of business. |
fleet_full | The company owns as many cars as its license allows. |
bid_too_low | The bid is not above the leading bid, or it is below the starting price. |
too_early | The order was announced and cannot be taken yet. |
starting | The starting car cannot be sold, and the starting driver cannot be dismissed. |
What can be read
Readable data has two parts: what everyone may read, and what only your company may read.
Public data
| Name | Stage | What it holds |
|---|---|---|
city | 1 | The tick, the day, the settings, the mechanics version. The seed is shown only in a solo city. |
city.map | 1 | Junctions, roads, places, districts. |
businesses | 1 | Every business: kind, place, business level, prices and stock. From stage 4 also its sales and profit for each of the last days. |
orders | 1 | Every open order: shop, items and weights, delivery fee, expiry, whether it can be taken yet (can_be_taken), and whether it is taken and by which car. From stage 4 the price limits. |
cars | 3 | Every car in the city: its company and where it is. |
markets.cars, markets.drivers | 2 | The offers, and for each the leading bid and its bidder. |
markets.business | 4 | The offers of shares, and for each the leading bid and its bidder. |
companies | 3 | Every company: its name, its colour, its place in the ranking, its wealth, the recent change of its wealth, and its recent profit. |
shares | 4 | For each business: who holds how many shares, and the controller. |
districts | 4 | Residents and what they want. |
Private data
| Name | Stage | What it holds |
|---|---|---|
me | 1 | Cash, held money, the loan and the loan limit, wealth, recent profit, licenses, and the running costs per tick. |
me.cars | 1 | Each car in full: fuel, tank, service level, capacity, cargo, taken orders, driver, state, target. |
me.drivers | 2 | Each driver: salary, multipliers, car, whether they are leaving and when. |
me.bids | 2 | Standing bids, and from stage 4 the company's own offers of shares. |
me.shares | 4 | Shares held, dividends received, and the businesses this company controls. |
me.businesses | 4 | For each business this company holds shares of: the account during the day, and the commands its controller sent with their reasons. For each one it controls: every setting. |
memory | 1 | The company's memory. |
Private data about another company cannot be read by any name.