Module api.cmd
The module is available on both the GUI State and the Engine State (and the Console State as well).
However, it works in a slightly different manner depending on where it is used from.
On the engine states, commands are executed immediately and the effects are immediately noticeable. Moreover, the callback function will be called immediately.
On the gui and console states, commands are executed in the next simulation step, and the effects are noticeable only after a few frames. The callback function will be called the frame after the command has been executed, after which the changes are visible on the gui and engine state.
Functions
| sendCommand(command[, callback]) | Sends a command object to be executed later or immediately depending on the state context. |
make
Functions
- sendCommand(command[, callback])
-
Sends a command object to be executed later or immediately depending on the state context. After the execution of the command, the callback function is called.
The callback function receives two parameters:
cmd the command that has been executed, depending on the context this might contain additional information. success a boolean value to indicate whether the command was successfulParameters:
- command Command the command object to be sent
- callback func(Command,bool) an optional function that is called after the execution of the command. (optional)
make
- make.bookJournalEntry(playerEntity, journalEntry[, a])
-
Makes a type.Book command.
When executed, the new journal entry is added to the players journal.
Parameters:
- playerEntity Entity the entity Id of the player
- journalEntry type.JournalEntry the entry to add
- a type.Vec3f position for the event (optional)
Returns:
- make.buildProposal(proposal, context, ignoreErrors)
-
Makes a type.BuildProposal command. This command is used to create new constructions and new streets via scripting.
When executed, the given build proposal is built. The command might fail resulting in the proposal not being built.
Parameters:
- proposal type.SimpleProposal a proposal containing a preview of the changes that will be applied with this command
- context type.Context or nil a context with extra options for the proposal
- ignoreErrors bool a flag enabling the building of the proposal even if non-critical errors are triggered
Returns:
-
type.BuildProposal
a newly created type.BuildProposal command
- make.buyVehicle(playerEntity, depotEntity, config)
-
Makes a type.BuyVehicle command.
When executed, a new vehicle is bought and placed in the given depot.
Parameters:
- playerEntity Entity the entity Id of the player
- depotEntity Entity the entity Id of the depot in which the vehicle will appear
- config type.TransportVehicleConfig data containing information about the vehicle being purchased
Returns:
-
type.BuyVehicle
a newly created type.BuyVehicle command
- make.connectTownsAndIndustries(townEntities, connections, keep)
-
Makes a type.ConnectTownsAndIndustries command.
When executed, the command generates a new street network connecting the given towns and all existing industries.
Parameters:
- townEntities {Entity,...} the entity Ids of the towns to connect together
- connections {type.Vec2i,...} list with indices type.Vec2i into the vector townEntities specifying which towns are to be connected
- keep bool set to true if existing street connections should be kept, otherwise the streets will be removed
Returns:
-
type.ConnectTownsAndIndustries
a newly created type.ConnectTownsAndIndustries command
- make.createLine(name, color, playerEntity, line)
-
Makes a type.CreateLine command.
When executed, creates a new line with the given parameters.
Parameters:
- name string the name of the new line
- color type.Vec3f the color of the new line
- playerEntity Entity the entity Id of the player owning the line
- line type.Line the configuration data for the line
Returns:
-
type.CreateLine
a newly created type.CreateLine command
- make.createTowns(towns)
-
Makes a type.CreateTowns command.
When executed, the command initiates the genration of new towns using information contained in type.TownInfo.
Parameters:
- towns {type.TownInfo,...} a list of town creation information, one for each new town
Returns:
-
type.CreateTowns
a newly created type.CreateTowns command
- make.deleteLine(lineEntity)
-
Makes a type.DeleteLine command.
When executed, the line with the given entity Id is removed.
Parameters:
- lineEntity Entity the line that should be removed
Returns:
-
type.DeleteLine
a newly created type.DeleteLine command
- make.developTown(world)
-
Makes a type.DevelopTown command.
When executed, the command triggers development of towns at the given position.
By developing towns, new buildings or street segments are added at the given position.
Parameters:
- world type.Vec2f position the position where development should be triggered
Returns:
-
type.DevelopTown
a newly created type.DevelopTown command
- make.instantlyUpdateTownCargoNeeds(townEntity, cargoNeeds)
-
Makes a type.InstantlyUpdateTownCargoNeeds command.
When executed, the cargo needs of the town districts are updated to the provided needs.
Parameters:
- townEntity Entity the entity Id of the town that should be updated
- cargoNeeds {{int,...},{int,...},{int,...}} a list of cargo type Ids for the needs of each of the three town districts residential, commercial and industrial.
Returns:
-
type.InstantlyUpdateTownCargoNeeds
a newly created type.InstantlyUpdateTownCargoNeeds command
- make.removeField(fieldEntity)
-
Makes a type.RemoveField command.
When executed, the field with the given entity Id is removed.
Parameters:
- fieldEntity Entity the entity Id of the field that should be removed
Returns:
-
type.RemoveField
a newly created type.RemoveField command
- make.removeTown(townEntity)
-
Makes a type.RemoveTown command.
When executed, the town with the given entity Id is removed (all streets and buildings belonging to the town will be removed as well).
Parameters:
- townEntity Entity the entity Id of the town that should be removed
Returns:
-
type.RemoveTown
a newly created type.RemoveTown command
- make.replaceTerrain(map, config, seedText, worldEntity, keepAssets)
-
Makes a type.ReplaceTerrain command.
When executed, the terrain is replaced. This is similar to the generation in map editor.
Parameters:
- map type.Map an object that specifies the data for the new terrain (heightmap, assets, water level...)
- config type.Terrain configuration parameters for the new terrain
- seedText string a seed for randomization purposes
- worldEntity Entity the entity Id of the world, usually 0
- keepAssets bool if set to true, existing landscape assets are conserved
Returns:
-
type.ReplaceTerrain
a newly created type.ReplaceTerrain command
- make.replaceVehicle(vehicleEntity, config)
-
Makes a type.ReplaceVehicle command.
When executed, the vehicle with the given entity Id will be replaced by the new vehicle configuration.
Parameters:
- vehicleEntity Entity the entity Id of the vehicle that should be replaced
- config type.TransportVehicleConfig data containing information about the new vehicle being purchased
Returns:
-
type.ReplaceVehicle
a newly created type.ReplaceVehicle command
- make.reverseVehicle(vehicleEntity)
-
Makes a type.Reverse command.
When executed, the vehicle with the given entity Id will be reversed.
Parameters:
- vehicleEntity Entity the entity Id of the vehicle that should be reversed
Returns:
-
type.Reverse
a newly created type.Reverse command
- make.sellVehicle(vehicleEntity)
-
Makes a type.SellVehicle command.
When executed, the vehicle with the given entity Id will be sold.
Parameters:
- vehicleEntity Entity the entity id of the vehicle that should be sold
Returns:
-
type.SellVehicle
a newly created type.SellVehicle command
- make.sendScriptEvent(fileName, id, name, param)
-
Makes a type.SendScriptEvent command. When executed, a script event will be broadcasted to all scripts.
Currently the script event must be fired within a script callback (e.g.
updateGui), it cannot be called from within, e.g., a GUI element callback. As workaround for this, the event can be store in a closure as follows:callbacks = {} ... local c = api.gui.comp.Slider.new("HORIZONTAL") c:onValueChanged(function(value) callbacks[#callbacks + 1] = api.cmd.sendCommand(api.cmd.make.sendScriptEvent(...)) end) ... guiUpdate = function() for k,v in pairs(callback) do v() end endParameters:
- fileName string the filename of the game_script that should be the pretended origin of the event
- id string identifier of the element that caused the event
- name string identifier of the event type
- param bool, number, string, table or nil parameters that depend on the context of the event
Returns:
-
type.SendScriptEvent
a newly created type.SendScriptEvent command
- make.sendToDepot(vehicleEntity, sellOnArrival)
-
Makes a type.SendToDepot command.
When executed, the vehicle with the given entity Id will be sent to the nearest reachable depot and (optionally) be sold.
Parameters:
- vehicleEntity Entity the entity Id of the vehicle that should be sent to the depot
- sellOnArrival bool if set to true, the vehicle will be sold upon arrival at the depot
Returns:
-
type.SendToDepot
a newly created type.SendToDepot command
- make.setAnimalState(animalEntity, movementType, targetChangedElapsed, invalidTileElapsed, movementSpeed, angularSpeed)
-
Makes a type.SetAnimalState command.
When executed, the animal with the given entity Id will be updated.
Parameters:
- animalEntity Entity the entity Id of the animal that should be updated
- movementType int the index of the configuration in the animals metadata movementTypes list
- targetChangedElapsed float time since the current target destination was selected
- invalidTileElapsed float time since the animal got into an invalid area
- movementSpeed float speed that should be used
- angularSpeed float angular speed that should be used
Returns:
-
type.SetAnimalState
a newly created type.SetAnimalState command
- make.setCalendarSpeed(millisecondsPerDay)
-
Makes a type.SetCalendarSpeed command.
When executed, the calendar speed is set to the given value (this affects only the speed of the calendar, and not the simulation speed).
Parameters:
- millisecondsPerDay int day length in milliseconds
Returns:
-
type.SetCalendarSpeed
a newly created type.SetCalendarSpeed command
- make.setColor(entity, color)
-
Makes a type.SetColor command.
When executed, the entity Id is set to the given color.
Parameters:
- entity Entity the entity Id of the entity that should be colored
- color type.Vec3f the rgb color
Returns:
-
type.SetColor
a newly created type.SetColor command
- make.setDate(date)
-
Makes a type.SetDate command.
When executed, the calendar date (for vehicle availability, etc.) is set to the given date.
Parameters:
- date type.Date the new date that should be set
Returns:
-
type.SetDate
a newly created type.SetDate command
- make.setGameSpeed(speed)
-
Makes a type.SetGameSpeed command.
When executed, the game (simulation) speed is set to the given value.
Parameters:
- speed double a positive number: the speed that the simulation will run at
Returns:
-
type.SetGameSpeed
a newly created type.SetGameSpeed command
- make.setLine(vehicleEntity, lineEntity, stopIndex)
-
Makes a type.SetLine command.
When executed, the vehicle with the provided entity Id is assigned to the line with given entity Id and sent to the stop with the given index.
Parameters:
- vehicleEntity Entity the entity Id of the vehicle that should be assigned to the line
- lineEntity Entity the entity Id of the line on which the vehicle should be sent
- stopIndex int the position of the stop on the line to which the vehicle should be sent to
Returns:
-
type.SetLine
a newly created type.SetLine command
- make.setName(entity, name)
-
Makes a type.SetName command.
When executed, the entity Id is renamed with the given name.
Parameters:
- entity Entity the entity Id of the entity that should be renamed
- name string the new name that should be set
Returns:
-
type.SetName
a newly created type.SetName command
- make.setSimBuildingClosureTimeStamp(simBuildingEntity, closureTimeStamp)
-
Makes a ??? command.
When executed, the command sets a new value to the closure time stamp of the given industry.
Parameters:
- simBuildingEntity Entity the entity Ids of the industry
- closureTimeStamp int sets the closure time of the insutry
Returns:
-
type.setSimBuildingClosureTimeStamp
a newly created ??? command
- make.setSimBuildingManualDevelopment(simBuildingEntity, manual)
-
Makes a ??? command.
When executed, the command sets the industry to manual mode if manual is true, or to automatic development mode of manual is set to false (default).
Parameters:
- simBuildingEntity Entity the entity Id of the building to set the development mode
- manual bool set to true if industries do not start to close/stop countdown and do not level up or down
Returns:
-
type.setSimBuildingManualDevelopment
a newly created ??? command
- make.setTownInfo(townEntity, initialLandUseCapacities)
-
Makes a type.SetTownInfo command.
When executed, the town with the given entity Id is set to the given initial capacities.
Parameters:
- townEntity Entity the entity Id of the town that should be updated
- initialLandUseCapacities {int,int,int} initial capacities for the residential, commercial and industrial districts of the town
Returns:
-
type.SetTownInfo
a newly created type.SetTownInfo command
- make.setUserStopped(vehicleEntity, userStopped)
-
Makes a type.SetUserStopped command.
When executed, the given vehicle is stopped or started as if the user controlled it in the vehicle dialog.
Parameters:
- vehicleEntity Entity the entity Id of the vehicle that should be stopped or started
- userStopped bool true if the vehicle should be stopped
Returns:
-
type.SetUserStopped
a newly created type.SetUserStopped command
- make.setVehicleManualDeparture(entity, manual)
-
Makes a type.SetVehicleManualDeparture command.
When an entity with component type.ComponentType.TRANSPORT_VEHICLE is set to manual departure
it will not depart from the terminal under any circumstance (the callback will always return success).
If the entity is not a transport vehicle, the command callback will return "False".
Parameters:
- entity Entity the entity Id of the vehicle of which the departure mode is to be changed
- manual bool whether the entity is managed or not
Returns:
-
type.SetVehicleManualDeparture
a newly created type.SetVehicleManualDeparture command
- make.setVehicleShouldDepart(vehicleEntity)
-
Makes a type.SetVehicleShouldDepart command.
When executed, and the vehicle with entity Id is at the terminal, the vehicle will immediately close
the door and depart as soon as the doors are closed. The vhehicle will ignore any departure condition and depart immediately.
The command callback will return success if the entity is has a type.ComponentType.TRANSPORT_VEHICLE component and
is currently waiting at the terminal.
Parameters:
- vehicleEntity Entity the entity Id of the vehicle at terminal that should depart
Returns:
-
type.SetVehicleShouldDepart
a newly created type.SetVehicleShouldDepart command
- make.setVehicleTargetMaintenanceState(vehicleEntity, value)
-
Makes a type.SetVehicleTargetMaintenanceState command.
When executed, the maintenance state for the vehicle with the given entity Id is set.
Parameters:
- vehicleEntity Entity the entity Id of the vehicle that should be stopped or started
- value float the maintenance level state that should be achieved
Returns:
-
type.SetVehicleTargetMaintenanceState
a newly created type.SetVehicleTargetMaintenanceState command
- make.spawnAnimal(fileName, position, lookAt)
-
Makes a type.SpawnAnimal command.
When executed, a new animal entity is spawned at the specified position.
Parameters:
- fileName string reference to the animal model for the animal that should be spawned
- position type.Vec2f world coordinates of the position where the animal should be spawned
- lookAt type.Vec2f the direction the animal is facin in
Returns:
-
type.SpawnAnimal
a newly created type.SpawnAnimal command
- make.updateLine(lineEntity, line)
-
Makes a type.UpdateLine command.
When executed, the line with the given entity Id is updated to the new line configuration.
Parameters:
- lineEntity Entity the entity Id of the line which should be updated
- line type.Line the new line configuration
Returns:
-
type.UpdateLine
a newly created type.UpdateLine command