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:

Lifecycle

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: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: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: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:setFrame (frame) Sets the current frame of the car.
car:setSpeed (speed) Returns the current target speed factor of the 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)

Class Car

This type represents Car objects.
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: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: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: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.
generated by LDoc 1.4.3 Last updated 2022-07-01 21:38:40