Lua API

• Index

Contents

• Functions
• Class Car

Modules

• Array
• Builder
• Building
• Car
• City
• DSA
• Debug
• Draft
• Drawing
• GUI
• NeighborCity
• Runtime
• Script
• TheoTown
• Tile
• Util
• Vector
• string

Topics

• Introduction
• Lua

Module Car

Car library for TheoTown.

This library provides general car related functions. Furthermore, objects of this type can be used to control cars after they have been spawned.

You can get a car object by Script car callback functions in your main script that will be called for cars whose storage table was set in the car spawn request Car.spawn(...). Such cars that were created with a storage table and therefore can be controlled afterwards are called smart cars as they can do potentially smart things. The smart car event functions will be called for all scripts that are attached to the draft that originally called Car.spawn(...). This concept is called car ownership and helps to only call the car event functions for scripts that are interested in it for the respective cars. There are no fixed callback functions that can be provided to Car.spawn(...) since these would not work after saving and re-loading the city (functions cannot be serialized in Lua). Instead you can use the storage table in the cars to store information in them that can be serialized.

This is how the lifecycle and event function calls for smart cars looks like:

This library was newly introduced in 1.10.51. It is only available while a city is open.

Functions

getCars ()	Returns an array of smart cars that are owned by the calling draft.
spawn (carDraft, startX, startY, targetX, targetY[, frame=nil[, storage=nil[, startLevel=nil[, targetLevel=nil]]]])	Spawns a car at a given position/position of a building that drives to the given target/building at the target.

Class Car

car:addTail (draft[, position=nil[, frame=-1]])	Adds a segment to the tail of a car.
car:despawn ()	Signals that the car should be deleted.
car:driveTo (x, y[, level=nil])	Will issue a new location for the car to drive to.
car:getCapacity ()	Returns the overall capacity of a car.
car:getDir ()	Returns the current direction of the car.
car:getDraft ()	Returns the car draft of the car.
car:getEffectiveSpeed ()	Returns the current effective speed of the car.
car:getFrame ()	Returns the current frame of the car.
car:getLevel ()	Returns the current height level of the car.
car:getSpeed ()	Returns the current target speed factor of the car.
car:getStorage ()	Returns the storage table of the car.
car:getTailDraft (position)	Returns the car draft of a tail segment.
car:getTailFrame (position)	Returns the car frame of a tail segment.
car:getX ()	Returns the current x tile position of the car.
car:getXY ()	Returns the current postion and level of the car all at once.
car:getY ()	Returns the current y tile position of the car.
car:isValid ()	Returns true iff this car is valid.
car:removeTail ([position=nil])	Removes a tail segment.
car:removeWholeTail ()	Removes the whole tail.
car:setFrame (frame)	Sets the current frame of the car.
car:setSpeed (speed)	Returns the current target speed factor of the car.
car:setTailFrame (position, frame)	Sets the car frame of a tail segment.
car:tailSize ()	Returns the size of the tail of a car.

Functions

getCars ()

Returns an array of smart cars that are owned by the calling draft. Since this is a potentially heavy operatin you should only call it at rare points in time e.g. when a city gets entered.

New feature:

This is a new feature that was added in version 1.10.51

Returns:

Array An array of cars that belong to the calling draft.

spawn (carDraft, startX, startY, targetX, targetY[, frame=nil[, storage=nil[, startLevel=nil[, targetLevel=nil]]]])

Spawns a car at a given position/position of a building that drives to the given target/building at the target. The car will actually not be spawned immediately but after a path has been calculated. This happens asynchronously since path calculation can take some time. You can provide a frame to determine the which variant of the car to use in case multiple variants are available. It will be choosen randomly by default.

New feature:

This is a new feature that was added in version 1.10.51

Parameters:

• carDraft draft
• startX int
• startY int
• targetX int
• targetY int
• frame int (default nil)
• storage table If you provide a table (may be empty) here the car will support smart car functionality like extended car event callbacks. (default nil)
• startLevel int (default nil)
• targetLevel int (default nil)

Usage:

 -- This script will wait for the player to tap on two buildings A and B.
 -- After that, it will spawn a police car from A that will drive to B and
 -- then back to A where it despawns.
 -- This will repeat indefinitely.
local carDraft = Draft.getDraft('$carpolice00')
local startBuilding, endBuilding

function script:enterCity()
  startBuilding, endBuilding = nil, nil
end

function script:earlyTap(x, y)
  local b = Tile.getBuilding(x, y)
  if b and not startBuilding then
    Debug.toast('Selected start building')
    startBuilding = b
    return false
  elseif b and not endBuilding then
    Debug.toast('Selected end building')
    endBuilding = b
    return false
  end
end

function script:onCarReached(car)
  local stg = car:getStorage()
  -- Drive back if first ending, otherwise do nothing -> car will despawn
  if stg.ctr == 0 then
    car:driveTo(stg.x, stg.y)
    stg.ctr = stg.ctr + 1
  end
end

function script:nextDay()
  if #Car.getCars() == 0 and startBuilding and endBuilding then
    -- Let's spawn a car
    Car.spawn(
      carDraft,
      startBuilding:getX(),
      startBuilding:getY(),
      endBuilding:getX(),
      endBuilding:getY(),
      nil,
      {
        x = startBuilding:getX(),
        y = startBuilding:getY(),
        ctr = 0
      }
    )
  end
end

Class Car

This type represents Car objects.

car:addTail (draft[, position=nil[, frame=-1]])

Adds a segment to the tail of a car.

New feature:

This is a new feature that was added in version 1.10.73

Parameters:

• draft draft A car draft that will be used for the tail segment. In case of nil a placeholder car ($car_null00) will be used.
• position int A one based tail index that indicates where the new tail segment should be inserted. If nil (default) the segment will appended at the end of the tail. (default nil)
• frame int A zero based variant index that will be used for the car. In case of -1 a random variant will be used. (default -1)

car:despawn ()

Signals that the car should be deleted. It may not be deleted immediately due to the asynchronous behavior of car updates.

New feature:

This is a new feature that was added in version 1.10.51

car:driveTo (x, y[, level=nil])

Will issue a new location for the car to drive to. Listening to smart car events will let you know whether the target can be reached.

New feature:

This is a new feature that was added in version 1.10.51

Parameters:

• x int The x tile position to target.
• y int The y tile position to target.
• level int The level to target. By default the game will try to match anything the car can drive to (e.g. buildings or roads). (default nil)

car:getCapacity ()

Returns the overall capacity of a car. The capacity of a car is a generic integer value defined in the car draft(s). The default capacity of a car draft is 0. This function returns the accumulated capacity of the car itself and its tail segments.

New feature:

This is a new feature that was added in version 1.10.73

Returns:

int The overall capacity of the car.

car:getDir ()

Returns the current direction of the car.

New feature:

This is a new feature that was added in version 1.10.51

Returns:

int The current direction of the car (1=SE, 2=NE, 4=NW, 8=SW)

car:getDraft ()

Returns the car draft of the car.

New feature:

This is a new feature that was added in version 1.10.51

Returns:

draft The car draft of the car.

car:getEffectiveSpeed ()

Returns the current effective speed of the car. The effective speed depends on road factors, car factors, target speed factors and so on.

New feature:

This is a new feature that was added in version 1.10.51

Returns:

float The current effective speed of the car.

car:getFrame ()

Returns the current frame of the car. The frame is actually the index of the variant determined by the total frames of the car / frames per variant. The first variant has index 0.

New feature:

This is a new feature that was added in version 1.10.51

Returns:

int The index of the current frame.

car:getLevel ()

Returns the current height level of the car.

New feature:

This is a new feature that was added in version 1.10.51

Returns:

int The height level of the car with 0 being ground.

car:getSpeed ()

Returns the current target speed factor of the car.

New feature:

This is a new feature that was added in version 1.10.51

Returns:

float The current target speed factor of the car.

car:getStorage ()

Returns the storage table of the car. The table was provided in the Car.spawn(...) car spawn request. Note that as usual you cannot store functions in the storage table as these cannot be serialized. (that means they won't be there after saving and loading the city)

New feature:

This is a new feature that was added in version 1.10.51

Returns:

table The storage table of the car.

car:getTailDraft (position)

Returns the car draft of a tail segment.

New feature:

This is a new feature that was added in version 1.10.73

Parameters:

• position int A one based tail index that indicates which tail segment should be queried.

Returns:

draft The car draft of the tail segment.

car:getTailFrame (position)

Returns the car frame of a tail segment.

New feature:

This is a new feature that was added in version 1.10.79

Parameters:

• position int A one based tail index that indicates which tail segment should be queried.

Returns:

draft The car frame of the tail segment.

car:getX ()

Returns the current x tile position of the car.

New feature:

This is a new feature that was added in version 1.10.51

Returns:

int The x tile position of the car.

car:getXY ()

Returns the current postion and level of the car all at once.

New feature:

This is a new feature that was added in version 1.10.51

Returns:

int,int,int The x, y tile position and level (0=ground) of the car.

car:getY ()

Returns the current y tile position of the car.

New feature:

This is a new feature that was added in version 1.10.51

Returns:

int The y tile position of the car.

car:isValid ()

Returns true iff this car is valid. You should dispose the handle in case the car is not valid anymore. You cannot respawn it.

New feature:

This is a new feature that was added in version 1.10.51

Returns:

bool True iff the car is valid, false otherwise.

car:removeTail ([position=nil])

Removes a tail segment.

New feature:

This is a new feature that was added in version 1.10.73

Parameters:

• position int A one based tail index that indicates which tail segment should be removed. (default nil)

Returns:

bool True iff a tail segment was removed.

car:removeWholeTail ()

Removes the whole tail.

New feature:

This is a new feature that was added in version 1.10.73

Returns:

bool True iff at least one tail segment was removed.

car:setFrame (frame)

Sets the current frame of the car. The frame is actually the index of the variant determined by the total frames of the car / frames per variant. The first variant has index 0.

New feature:

This is a new feature that was added in version 1.10.51

Parameters:

• frame int The frame to set.

car:setSpeed (speed)

Returns the current target speed factor of the car.

New feature:

This is a new feature that was added in version 1.10.51

Parameters:

• speed float The target speed factor of the car. Normal is 1.0.

car:setTailFrame (position, frame)

Sets the car frame of a tail segment.

New feature:

This is a new feature that was added in version 1.10.79

Parameters:

• position int A one based tail index that indicates which tail segment should be modified.
• frame int The frame to set.

car:tailSize ()

Returns the size of the tail of a car.

New feature:

This is a new feature that was added in version 1.10.73

Returns:

int Size of the tail. If the result is 0 then there is no tail.