Module Admin

Provides administrative superpowers to a stage control program.

Functions

destroyShip (ship) Destroys a ship.
drawText (text, x, y, size, color, duration) Draws text on the screen.
gameOver () Ends the match.
moveShip (ship, x, y) Moves a ship.
reviveShip (ship) Revives a ship.
roundOver () Ends a round.
sendEvent (ship, event) Sends a custom event to the target ship.
setRank (ship, rank) Sets the rank of a ship or team (lower is better).
setScore (ship, score) Sets the score of a ship or team.
setShipEnergy (ship, energy) Sets a ship's energy.
setShipEnergyEnabled (ship, enabled) Sets whether a ship's energy can be modified.
setShipHeading (ship, heading) Sets a ship's heading, in radians (0 is east, pi / 2 is north).
setShipLaserEnabled (ship, enabled) Sets whether a ship's laser gun is enabled.
setShipShowName (ship, showName) Sets whether a ship's name is drawn on screen.
setShipSpeed (ship, speed) Sets a ship's speed.
setShipThrusterEnabled (ship, enabled) Sets whether a ship's thruster is enabled.
setShipTorpedoEnabled (ship, enabled) Sets whether a ship's torpedo gun is enabled.
setStatistic (ship, key, score, value) Sets a statistic for a ship or team.
setWinner (name, ship) Sets the ship or team that has won the match.
shipDamage (ship) Returns the amount of damage the given ship has done to enemy ships.
shipFriendlyDamage (ship) Returns the amount of damage the given ship has done to friendly ships (self or teammates).
shipFriendlyKills (ship) Returns the number of friendly ships (self or teammates) the given ship has killed.
shipKills (ship) Returns the number of enemy ships the given ship has killed.


Functions

destroyShip (ship)

Destroys a ship.

Parameters

  • ship: The ship to destroy.
drawText (text, x, y, size, color, duration)

Draws text on the screen.

Parameters

  • text: The text to draw on the screen.
  • x: The x coordinate of the left side of the text.
  • y: The y coordinate of the bottom of the text.
  • size: (optional) Size of characters, in pixels. Default is 28.
  • color: (optional) The color of the text. Default is white.
  • duration: (optional) The number of ticks, in game time, that the text will stay on screen. Default is 1.
gameOver ()

Ends the match. The gameOver function is called on any ship control program that defines it.
moveShip (ship, x, y)

Moves a ship. If the specified location overlaps any walls or other ships, it is shifted randomly until it doesn't.

Parameters

  • ship: The ship to move.
  • x: The x coordinate of the ship's new location.
  • y: The y coordinate of the ship's new location.
reviveShip (ship)

Revives a ship.

Parameters

  • ship: The ship to revive. The ship's energy is set to full (100).
roundOver ()

Ends a round. All lasers and torpedos are removed from the stage. All user ships are revived and moved to new start locations by the same process as at the start of a match. Stage ships and disabled ships are unchanged. The roundOver function is called on any ship control program that defines it.
sendEvent (ship, event)

Sends a custom event to the target ship. This event can be any Lua value - nil, boolean, number, string, or a table containing any of these values, including nested tables.

Parameters

  • ship: The ship to send the event to.
  • event: The value to send as an event.
setRank (ship, rank)

Sets the rank of a ship or team (lower is better). If no winner is set, a ship or team with rank 1 is the winner.

Parameters

  • ship: The ship or team for which to set the rank. This can be the name of the ship or team or the userdata object of any ship on the team.
  • rank: The rank of the ship or team (lower is better). This must be an integer.
setScore (ship, score)

Sets the score of a ship or team. If no ranks are set by the stage program, teams are assigned ranks based on highest scores.

Parameters

  • ship: The ship or team for which to set score. This can be the name of the ship or team or the userdata object of any ship on the team.
  • score: A numeric score.
setShipEnergy (ship, energy)

Sets a ship's energy.

Parameters

  • ship: The ship to modify.
  • energy: The new energy of the ship.
setShipEnergyEnabled (ship, enabled)

Sets whether a ship's energy can be modified. (Default: false, or true if battle mode is enabled.)

Parameters

  • ship: The ship to modify.
  • enabled: true to enable energy tracking for the ship, false otherwise.
setShipHeading (ship, heading)

Sets a ship's heading, in radians (0 is east, pi / 2 is north). The ship will have the chance to fire its thruster once more before its position is next updated.

Parameters

  • ship: The ship to modify.
  • heading: The new heading of the ship.
setShipLaserEnabled (ship, enabled)

Sets whether a ship's laser gun is enabled. (Default: false, or true if battle mode is enabled.)

Parameters

  • ship: The ship to modify.
  • enabled: true to enable the ship's laser gun, false otherwise.
setShipShowName (ship, showName)

Sets whether a ship's name is drawn on screen. Setting this to false also hides the ship from the dock in the BerryBots GUI. (Default: true.)

Parameters

  • ship: The ship to modify.
  • showName: true to show the ship's name, false otherwise.
setShipSpeed (ship, speed)

Sets a ship's speed. The ship will have the chance to fire its thruster once more before its position is next updated.

Parameters

  • ship: The ship to modify.
  • speed: The new speed of the ship.
setShipThrusterEnabled (ship, enabled)

Sets whether a ship's thruster is enabled. (Default: true.)

Parameters

  • ship: The ship to modify.
  • enabled: true to enable the ship's thruster, false otherwise.
setShipTorpedoEnabled (ship, enabled)

Sets whether a ship's torpedo gun is enabled. (Default: false, or true if battle mode is enabled.)

Parameters

  • ship: The ship to modify.
  • enabled: true to enable the ship's torpedo gun, false otherwise.
setStatistic (ship, key, score, value)

Sets a statistic for a ship or team. These are for auxiliary scoring or statistical data - they have no effect on scores, ranks, or winners.

Parameters

  • ship: The ship or team for which to set a statistic. This can be the name of the ship or team or the userdata object of any ship on the team.
  • key: A string describing the statistic.
  • score:
  • value: A numeric value.
setWinner (name, ship)

Sets the ship or team that has won the match. Also assigns rank 1 to the ship or team.

Parameters

  • name:
  • ship: The ship or team that won the match. This can be the name of the ship or team or the userdata object of any ship on the team.
shipDamage (ship)

Returns the amount of damage the given ship has done to enemy ships. The amount of damage is divided by the total energy a ship starts with. If a ship inflicts full damage to a ship, that would be 1.0 damage.

Parameters

  • ship: The ship to query.
shipFriendlyDamage (ship)

Returns the amount of damage the given ship has done to friendly ships (self or teammates). The amount of damage is divided by the total energy a ship starts with. If a ship inflicts full damage to a ship, that would be 1.0 damage.

Parameters

  • ship: The ship to query.
shipFriendlyKills (ship)

Returns the number of friendly ships (self or teammates) the given ship has killed.

Parameters

  • ship: The ship to query.
shipKills (ship)

Returns the number of enemy ships the given ship has killed.

Parameters

  • ship: The ship to query.