Skip to content
Alpha version. These pages describe a game that is not built yet. Everything here can still change, and in the alpha every city can be reset at any time.

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 ​

EventStageCarriesMeaning
idle1car, whyA 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 ​

EventStageCarriesMeaning
fuel_below(x)1car, fuelThe car's fuel dropped below the limit x that the code chose.
service_below(x)1car, service_levelThe same for the service level.
car_broke_down1car, cause, fineThe car ran out of fuel, or its service level reached zero. The fine was charged.
driver_quitting2driver, car, ticks_leftA driver announced that they leave.
driver_left2driver, carThe driver left. The car cannot move until another driver is assigned.

Orders ​

EventStageCarriesMeaning
orders_changed1added, taken, goneThe set of orders changed. One event covers all changes of a tick.
taken_order_expired1order, car, penaltyAn order that one of this company's cars had taken ran out of time. From stage 3 the penalty was charged.
command_failed1command, codeA 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 ​

EventStageCarriesMeaning
offer_added2market, offerA new offer is on a market.
offer_removed2market, offerAn offer left a market without being sold.
bid_placed2offer, leading_bid, leaderSomeone bid on an offer. Sent to everyone who can see the market.
auction_closed2offer, winner, amountAn auction ended. A bidder who lost has their held money back.

Money ​

EventStageCarriesMeaning
payment1kind, amount, what it was forMoney came in or went out in one piece: a delivery fee, a fine, a purchase, a dividend.
loan_changed1loan, limit, whyThe company's loan changed: it took or repaid a loan, or the bank lent by itself.
forced_sale2what was sold, for how muchThe 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 ​

EventStageCarriesMeaning
company_left3companyA company left the city.

Businesses and the city ​

EventStageCarriesMeaning
day_ended1day, a summary of the company's dayA day is over. Interest was charged. From stage 4 dividends and losses were settled too.
shares_changed4business, who holds whatShares of a business changed hands.
control_changed4business, controllerA business has a new controller, or none. Sent to its shareholders.
stock_below(x)4business, item, amountStock in a business this company controls dropped below the limit the code chose.
city_grew4step, the new part of the mapThe city grew by one step.

The code itself ​

EventStageCarriesMeaning
started1version, whyThe code just started: first start, a new push, a restart, or after a crash.
action_called5action, values, callerSomeone 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 ​

CommandStageMeaning
car.go_to(place)1Drive to a place by the shortest route.
car.load(order)1At 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)1At the order's shop, with all its goods on board: hand them over and receive the delivery fee.
car.refuel(amount)1At a fuel station: fill the tank, or add the given amount.
car.service()1At a service station: restore the service level.
car.halt()1Stop driving and stand at the next place.
car.sell_to_city()2Sell the car to the city for its market value. The car must be empty and at a place.

Drivers ​

CommandStageMeaning
driver.assign(car)2Assign the driver to a car. A driver already in that car becomes a spare driver.
driver.unassign()2Take the driver out of their car.
driver.dismiss()2Stop employing the driver.

Licenses and markets ​

CommandStageMeaning
buy_license(kind, level)2Buy a fleet license level, or from stage 4 a business license.
take_loan(amount)2Borrow from the bank, up to the loan limit.
repay_loan(amount)2Pay back a part or all of the loan.
bid(offer, amount)2Place a bid, or raise your own.
cancel_bid(offer)2Take your bid back.

Shares ​

CommandStageMeaning
offer_shares(business, count, starting_price)4Put a lot of your shares on the business market.
withdraw_offer(offer)4Take your offer back, if nobody has bid on it.
sell_shares_to_city(business, count)4Sell shares to the city for their market value.

Running a business ​

Only the controller of the business may send these.

CommandStageMeaning
shop.set_retail_price(item, price)4Set what residents pay.
shop.post_order(items, fee, price_limits, expiry)4Post an order.
shop.set_stock_list(items)4Choose which items the shop stocks.
storage.set_wholesale_price(item, price)4Set what shops pay.
storage.set_stock_plan(item, amount)4Choose how much of an item the storage brings in.
fuel_station.set_price(price)4Set the fuel price.
service_station.set_price(price)4Set the service price.
business.upgrade()4Pay for the next business level.
business.use_built_in(setting)4Hand 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 ​

OperationStageMeaning
declare_action(name, parameters, text)5Tell the game about an action that others may call.
answer(call, value)5Send an answer to whoever called an action.
publish(name, value)5Show a value on the control panel.

Memory and notes ​

OperationStageMeaning
memory[name] = value, memory[name], del memory[name]1Write, read and remove a value in the company's memory.
log(text)1Write a line into the company's log.
city.route_length(a, b)1The length of the shortest route between two places. The game answers it, with its own route finding.
city.nearest(place, kind)1The 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.

OperationStageMeaning
changes(since)1Get the events and the changed data since a tick.
restart_code()1Restart the company's uploaded code.
code_status()1Which version runs, the state of the last push, and recent errors.
call_action(name, values)5Call an action the uploaded code declared, and get its answer.
decisions(filter)1Read 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)1Read the company's log from a tick on.
check_code(files)1Ask whether this code would be accepted, without pushing it.
cities()1The player's cities, and the listed shared cities, each marked as a lobby or as running. Only a lobby can be joined.
actions()5The 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.

HelperStageMeaning
car.free_capacity1The car's capacity minus its cargo.
car.has_all(order)1Whether the car carries every item of the order.
order.weight1The total weight of the order's items.
order.next_storage(car)1Among 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.

CodeMeaning
not_yoursThe car, driver or business does not belong to this company, or it does not control it.
unknownNo such car, order, place or offer.
no_driverThe car has no driver assigned.
broken_downThe car has broken down and waits for its recovery.
wrong_placeThe car is not at the place this command needs.
no_routeNo road leads there.
order_takenAnother car has taken this order.
order_goneThe order expired or was delivered.
too_heavyThe order does not fit into the car's free capacity.
not_in_stockThe storage has none of the items the car still needs.
over_price_limitThe storage's wholesale price is above the order's price limit.
goods_missingThe car does not carry all goods of the order.
no_cashThe company cannot pay for this.
over_loan_limitThe company's loan is above its loan limit, so it cannot buy, bid or borrow more.
license_neededThe company lacks the license this needs. This includes bidding on shares without the license for that kind of business.
fleet_fullThe company owns as many cars as its license allows.
bid_too_lowThe bid is not above the leading bid, or it is below the starting price.
too_earlyThe order was announced and cannot be taken yet.
startingThe 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 ​

NameStageWhat it holds
city1The tick, the day, the settings, the mechanics version. The seed is shown only in a solo city.
city.map1Junctions, roads, places, districts.
businesses1Every business: kind, place, business level, prices and stock. From stage 4 also its sales and profit for each of the last days.
orders1Every 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.
cars3Every car in the city: its company and where it is.
markets.cars, markets.drivers2The offers, and for each the leading bid and its bidder.
markets.business4The offers of shares, and for each the leading bid and its bidder.
companies3Every company: its name, its colour, its place in the ranking, its wealth, the recent change of its wealth, and its recent profit.
shares4For each business: who holds how many shares, and the controller.
districts4Residents and what they want.

Private data ​

NameStageWhat it holds
me1Cash, held money, the loan and the loan limit, wealth, recent profit, licenses, and the running costs per tick.
me.cars1Each car in full: fuel, tank, service level, capacity, cargo, taken orders, driver, state, target.
me.drivers2Each driver: salary, multipliers, car, whether they are leaving and when.
me.bids2Standing bids, and from stage 4 the company's own offers of shares.
me.shares4Shares held, dividends received, and the businesses this company controls.
me.businesses4For 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.
memory1The company's memory.

Private data about another company cannot be read by any name.

Delivery is part of simgit.io. This is an alpha version.